Errors
Standard error response shape and common error codes.
Mercel uses conventional HTTP status codes to signal success or failure. 2xx indicates success, 4xx indicates a client error (bad request, missing permissions, not found), and 5xx indicates a server error.
Error response shape
Every non-2xx response has the same JSON body:
{
"error": {
"code": "string",
"message": "string",
"details": null
}
}code— a stable machine-readable identifier (e.g.UNAUTHORIZED,NOT_FOUND,VALIDATION,RATE_LIMITED).message— a human-readable description, suitable for logging.details— optional structured payload. ForVALIDATIONthis contains the offending fields and Zod issues; forRATE_LIMITEDit carries{ retryAfterMs }.
Common codes
| HTTP status | Code | When |
|---|---|---|
| 400 | VALIDATION | Request body or query parameters failed schema validation. |
| 401 | UNAUTHORIZED | Missing or invalid Authorization header. |
| 403 | FORBIDDEN | Authenticated, but the credential cannot access the target resource (e.g. a credential used against a store it isn't bound to, or a PAT used for a write). |
| 404 | NOT_FOUND | Resource does not exist or is not visible to you. |
| 409 | CONFLICT | The request conflicts with current resource state (e.g. a slug already in use). |
| 429 | RATE_LIMITED | Per-key rate limit exceeded — see Rate limits. |
| 500 | INTERNAL | An unexpected error occurred. Includes a correlation id you can share with support. |
Correlation ids
Every response carries an X-Correlation-Id header. Include it when reporting issues so we can find the request quickly.