Errors
One error format, with stable codes to branch on.
Every failed request returns a non-2xx status and the same body:
{
"error": {
"type": "conflict",
"code": "invalid_transition",
"message": "Fulfillment can't move from delivered to shipped.",
"param": "fulfillment_status",
"request_id": "req_8RojGGDMGfh1js_r"
}
}| Field | Use it for |
|---|---|
type | The broad category — matches the HTTP status |
code | Branch on this. Stable; new codes may be added |
message | A human-readable explanation. May change — don't parse it |
param | The request field the error is about, or null |
request_id | Also in the X-Request-Id header. Quote it to support |
All codes
| Status | type | code |
|---|---|---|
| 400 | invalid_request | validation_failed |
| 400 | invalid_request | invalid_cursor |
| 401 | authentication | missing_api_key |
| 401 | authentication | invalid_api_key |
| 401 | authentication | expired_api_key |
| 401 | authentication | revoked_api_key |
| 403 | permission | insufficient_scope |
| 403 | permission | plan_required |
| 404 | not_found | resource_not_found |
| 409 | conflict | invalid_transition |
| 409 | conflict | insufficient_stock |
| 409 | conflict | idempotency_mismatch |
| 409 | conflict | idempotency_in_progress |
| 429 | rate_limit | rate_limited |
| 500 | api_error | internal_error |
Handling them
400— fix the request; retrying the same one fails again.parampoints at the field.401/403— check the key, its scopes and the store's plan. See Authentication.404— the id doesn't exist in this store. A key never sees another store's data.409— the change isn't allowed in the record's current state, e.g. an invalid fulfillment step or not enough stock. Re-read the record first.429— wait forRetry-Afterseconds. See Rate limits.500— something failed on our side. Retry with backoff, using an Idempotency-Key for writes.