Errors

All errors follow a consistent JSON format.

Error format

{
  "success": false,
  "message": "A human-readable description of what went wrong"
}

Validation errors include additional fields:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": "email required",
    "amount": "must be positive"
  }
}

Code	Meaning	Typical cause
`200`	OK	Successful GET or PATCH
`201`	Created	Successful POST that created a resource
`400`	Bad Request	Missing required parameter, invalid JSON, business rule violated
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Key valid but missing required scope
`404`	Not Found	Resource doesn't exist or isn't in your tenant
`409`	Conflict	Duplicate (e.g. email already exists)
`429`	Too Many Requests	Rate limit exceeded — check `Retry-After` header
`500`	Internal Server Error	Unexpected server error — contact support

Message	What to do
`API key required`	Send `Authorization: Bearer spk_...` header
`Invalid or expired API key`	Key is revoked, expired, or typo'd — check and regenerate
`Missing required scope: X`	Key doesn't have the scope needed for this endpoint
`Hourly rate limit exceeded`	Wait and retry; consider upgrading tier
`Cart not found`	Cart ID doesn't exist or expired
`Order is not eligible for return`	Order must be in `shipped` or `delivered` status

Idempotent operations (GET, PATCH) can be retried on 5xx or network errors
Non-idempotent operations (POST) should NOT be retried blindly — you may create duplicates. Check the resource first, or use idempotency keys (coming soon).
Use exponential backoff: wait 1s, 2s, 4s, 8s, etc.
Give up after ~5 attempts — if the API is down longer than that, your own system should handle the degradation.