Errors

Format

API errors are JSON:

{
  "status_code": 404,
  "detail": "Not Found",
  "extra": {}
}

Field	Meaning
status_code	HTTP status code, identical to the response status
detail	Short message in English. Meant for people, not for evaluation.
extra	Optional. Machine-readable details, often with a code in extra.error. Evaluate values, never detail.

Tell cases apart by extra.error. Every operation in the reference lists its codes.

Status codes

Status	Meaning	Retry?
400	The request is malformed or violates a rule (missing field, wrong type, invalid value). extra.error names the reason when present.	No, fix first
401	Not signed in, or token invalid or expired	No, see Authentication
403	No matching permission, or key revoked	No, see Scopes
404	Does not exist or belongs to another account	No
409	Conflict with the current state, for example an action that is no longer possible in the resource’s status. extra.error names the reason.	Re-read the state first
413	Upload too large	No, shrink the file
422	The request is understood but cannot be carried out for business reasons, for example preview errors or IDEMPOTENCY_KEY_REUSED	No, fix first
429	Too many requests, see Rate limits	Yes, after waiting
5xx	Error or disruption on Shirtee’s side	Yes, with backoff

Retrying

• Retry only 429 and 5xx, with growing delay (backoff) and an upper bound.
• Retry write calls only when they are repeatable. For order creation that means Idempotency-Key.
• Platform errors do not always arrive as JSON. A 502 or 504 can be an HTML error page. Evaluate the status code first, then the body.

Reading the response

Check the status code before you parse the body as JSON. Your client should ignore unknown fields in responses, see Stability and changes.