Errors

Milkloud /v1 APIs report failures with an HTTP status and the common response envelope. Use code for the exact recovery path; message is localized and can change.

Authentication Errors

The authenticated /v1 endpoints in this guide can return these common errors before the endpoint logic runs:

HTTP status	Code	Meaning	Client action
401	TokenExpireError	A Bearer access token is missing, malformed, expired, or revoked.	If an approved OIDC client has a refresh token, refresh once and retry once. Otherwise, start authorization again.
401	IllegalTokenError	The Bearer credential is not an accepted API access token because of its type, audience, or required claims.	Send the API access token issued for this client. Do not send an ID token, refresh token, or first-party web-session token.
401	TokenInvalidError	A User Token is malformed, expired, revoked, deleted, or otherwise no longer valid.	Ask the user to create a replacement User Token and update the stored secret.
403	PermissionError	The credential cannot perform the operation because of its token type, scope, or target user.	Do not retry unchanged. Use the API access token, request the required scope, or correct the target identity.

Common API Errors

These errors are not specific to one operation:

HTTP status	Code	Meaning	Client action
400	RequestParamError	A path, query value, header, or request body is invalid.	Fix the request before retrying.
404	PageNotFound	The API path does not exist.	Check the selected API base, version, and endpoint path.
429	ThrottlingError	Requests from this authenticated user are arriving too quickly.	Retry with exponential backoff and jitter. Do not retry in a tight loop.
500	InternalServerError	The service could not complete the request.	Retry only idempotent operations with bounded backoff. Surface a persistent failure to the user.
500	DBError	A service data-store operation failed.	Treat it like InternalServerError; do not change the request based on the localized message.

An endpoint can define a more specific error. Prefer its endpoint-specific recovery.

Retry Rules

• Retry transient 429 or 500 responses only for safe or known-idempotent operations, with bounded exponential backoff and jitter. Milkloud does not always return Retry-After.
• Do not retry 400, 403, or 404 unchanged.

OIDC Protocol Errors

OIDC endpoints use standard OIDC and OAuth errors rather than the /v1 response envelope. Handle them through the OIDC client library.