Error codes with Meridian
Every Meridian API error response includes a machine-readable code, a human-readable message, and a unique request ID for tracing.
| Code | Meaning | How to handle |
|---|---|---|
| 400 | Bad Request The request body is malformed, missing required fields, or contains invalid JSON. | Validate payloads against the schema before sending. Check Content-Type is application/json. |
| 401 | Unauthorized No valid session token was provided, or the token has expired. | Call /auth/refresh to obtain a new token pair. If refresh fails, redirect to login. |
| 402 | Payment Required The account lacks an active subscription or has exhausted its quota. | Present the billing portal URL from the response body. Do not retry without user action. |
| 403 | Forbidden The authenticated principal lacks permission for the requested resource. | Check the scopes claim in the access token. Request elevation if the UX allows it. |
| 404 | Not Found The endpoint or resource does not exist, or the ID references a deleted object. | Verify the resource ID and API version path. Treat as terminal for that request. |
| 429 | Too Many Requests The client has exceeded the rate limit for the current window. | Read the Retry-After header and wait that many seconds before the next attempt. |
| 500 | Internal Server Error An unexpected condition prevented the server from fulfilling the request. | Log the request ID from the X-Request-Id header. Retry with exponential backoff up to 3 times. |
| 502 | Bad Gateway An upstream service returned an invalid response. | Retry with jitter after 1–2 seconds. Escalate if the error persists beyond 30 seconds. |
| 503 | Service Unavailable The server is temporarily overloaded or down for maintenance. | Honor the Retry-After header. Switch to a stale-while-revalidate cache if available. |