Errors

Every /v1 error - whatever the cause - has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": {},
    "requestId": "req_AbCdEfGh12345678"
  }
}

• code - a stable, machine-readable string. Match your error-handling logic on this field.
• message - human-readable, not localized, and not guaranteed to be stable wording between releases - don’t match on it.
• details - additional machine-readable context where relevant (e.g. which scopes were required); an empty object when there’s nothing more to add.
• requestId - the same value as the X-Request-Id response header. Include it when reporting a problem.

Error codes

HTTP status	code	Meaning
400	validation_failed	The request’s query parameters failed validation (wrong type, out of range, malformed date, etc.).
401	unauthorized	Missing, malformed, expired or revoked API key, or the owning client is disabled/revoked.
403	scope_denied	The key is valid but doesn’t hold the scope this route requires.
404	not_found	The resource doesn’t exist, or exists outside your tenant/allowed stores. Both cases return the same generic 404 deliberately - see Products and API Overview.
413	payload_too_large	The request exceeded the configured size limit.
429	rate_limited	Too many requests - see Rate Limits.
500	internal_error	An unexpected server error. The message is deliberately generic; use requestId when reporting it.

This is the complete list. No other code value is part of the contract - if you see something else, something unexpected happened and it’s worth reporting with the request ID.

Handling errors in your integration

• Branch on code, not on the HTTP status alone (a 404 for “resource doesn’t exist” and a 404 for “outside your access” both need the same handling in practice: don’t retry, don’t assume the ID is wrong forever).
• Treat 401/403 as non-retryable configuration problems, not transient failures - see Key Revocation.
• Treat 429 as retryable with backoff - see Rate Limits.
• Treat 500 as retryable, sparingly, with backoff - and report it if it persists.
• See Examples → Handle an error for a concrete snippet.