Errors

Open API v2 errors use the RFC 9457 application/problem+json format. Per-recipient failures in an issuance batch are the exception (always 200 + BatchResultDto — see Concepts).

Problem shape

{
  "type": "https://api.kolleges.net/probs/token-scope-insufficient",
  "title": "Token scope insufficient",
  "status": 403,
  "detail": "The token is missing the kolleges:openapi:issuance:write scope.",
  "instance": "/v2/clubs/acme/issuances"
}

type is an error-code identifier (not a URL you fetch). Two representative codes are kept separate for diagnosis: token-scope-insufficient (the token lacks the scope) and link-scope-insufficient (no permission for that club).

Status codes

Code	Meaning	What to do
400	Malformed request (schema violation)	Fix the body/query
401	Missing, expired, tampered, or wrong-audience token	Re-issue the token
403	Insufficient scope · no club permission	Re-issue the token with the required scope
404	Resource not found	Check the path and id
409	Idempotency conflict · state conflict	Check the idempotency key and current state
422	Domain-rule violation	See detail
429	Rate limit exceeded	Back off and retry
5xx	Server error	Retry with exponential backoff

401 vs 403

401 is an authentication failure (the token is not valid) — re-issue the token. 403 is an authorization failure (the token is valid but lacks permission) — re-issuing the token won’t fix it. Check the scopes registered on the client and the club permission.

Retry strategy

• 5xx · 429 · network failure → retry with exponential backoff. For writes, retry with the same Idempotency-Key to prevent duplicate issuance.
• 4xx (except 429) → retrying yields the same failure. Read detail and fix the request.

Idempotent retries

Because tokens expire every 15 minutes, if you hit a 401 during a long batch, just re-issue the token and resume with the same Idempotency-Key — recipients already processed won’t be issued twice.