REST API·intermediate·3 min
Errors & status codes
The error envelope and every code Catalyte can return.
Every error returns the same envelope, regardless of endpoint:
{
"error": {
"code": "plan_limit",
"message": "Free plan allows 100 products. You have 100.",
"request_id": "req_01HZK..."
}
}code is stable across versions and safe to switch on. message is human-readable and may change. request_id ties to the entry in Logs.
Status codes
| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_request, validation_failed | The body or query is malformed. |
| 401 | unauthorized, invalid_token | No or bad bearer token. |
| 402 | plan_limit | Your plan blocks the action. Upgrade or remove items. |
| 403 | forbidden, scope_missing | Token lacks the scope. |
| 404 | not_found | No resource at that id. |
| 409 | sku_conflict | SKU already exists in this workspace. |
| 422 | validation_failed | Specific field violated a constraint. |
| 429 | rate_limited | Slow down. Retry-After header included. |
| 500 | internal_error | On us. Send us the request_id. |
Idempotency
POST endpoints accept an Idempotency-Key header. Repeated requests within 24 hours return the original response — useful for safe retries on network blips.