---
url: https://milthm.cn/wiki/en/manual/developer/milkloud/errors.md
description: Handle Milkloud API errors and authentication failures.
---

# Errors

Milkloud `/v1` APIs report failures with an HTTP status and
the [common response envelope](https://milthm.cn/wiki/en/manual/developer/milkloud.md#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.