Error Codes

All error responses use the same envelope:

{
  "success": false,
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable description."
  },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "version": "v1"
  }
}

The error.code field is stable and machine-readable. The error.message is human-readable and may change.

Authentication Errors

Code	HTTP	Description
api_platform_disabled	503	The API platform is currently disabled by the operator. Try again shortly or contact support.
missing_credentials	401	No X-API-Key header or Authorization: Bearer header was provided.
malformed_credentials	401	A credential header was present but could not be parsed (e.g. a malformed Bearer header).
invalid_api_key	401	The API key does not match any active key in the system.
expired_token	401	The Bearer token has passed its expiry time. Request a new token via the token endpoint.
revoked_api_key	403	The API key has been explicitly revoked. Obtain a new key from your account manager.
revoked_token	403	The Bearer token has been explicitly revoked. Request a new token.
client_suspended	403	Your API client account has been suspended. Contact support.
ip_not_allowed	403	The request originated from an IP address not in your allowlist. Contact your account manager to update the list.
credential_environment_mismatch	403	A live credential was used against a sandbox endpoint, or vice versa. Use the correct key/token for the target environment.

Authorization Errors

Code	HTTP	Description
scope_missing	403	The endpoint requires a scope that your credential does not have. Contact your account manager to discuss expanded access.
api_access_disabled	403	API access has not been enabled for your account. Contact support.
api_write_scope_not_commercially_enabled	403	Write endpoints require enterprise access, which is not enabled for your account.

Rate Limit & Allowance Errors

Code	HTTP	Description
rate_limit_exceeded	429	You have exceeded the per-minute request rate for your tier. Wait until the X-RateLimit-Reset timestamp and retry.
api_usage_allowance_exceeded	429	Your monthly request allowance has been exhausted. Contact your account manager to discuss overage options.

Endpoint & Platform Errors

Code	HTTP	Description
endpoint_disabled	503	This specific endpoint (or its category) has been temporarily disabled. The error.message will contain any available detail. Retry later.
idempotency_conflict	409	An Idempotency-Key was reused with a different request body. Generate a new unique key for each distinct operation.

Request Errors

Code	HTTP	Description
invalid_request	400	A required parameter is missing or has an invalid value. See the error.message for which parameter.
invalid_grant	400	Token endpoint: the grant_type is not client_credentials.
invalid_client	401	Token endpoint: the client_id/client_secret pair is invalid.
invalid_scope	400	Token endpoint: the requested scope is not a subset of your allowed scopes.

Server Errors

Code	HTTP	Description
internal_error	500	An unexpected server error occurred. Include the X-Request-Id when contacting support.

Retry Guidance

HTTP Status	Safe to retry?	Notes
400	No	Fix the request first.
401 (expired)	Yes, after re-auth	Re-request a token then retry.
401 (other)	No	Credential issue - contact support.
403	No	Access denied - won't change on retry.
409	No (change key)	Use a new Idempotency-Key.
429 (rate limit)	Yes, after reset	Wait until X-RateLimit-Reset.
429 (allowance)	No	Monthly quota exhausted.
500	Yes, with backoff	Retry once with exponential backoff; if persistent, contact support with X-Request-Id.
503 (disabled)	Yes, later	Poll for restoration; contact support if urgent.