Error codes

Every non-2xx response returns the same JSON envelope. The code is stable and safe to switch on; the message is human-readable and may change.

Envelope

{
  "error": {
    "code": "insufficient_scope",
    "message": "Required scope(s): consumer.documents.read"
  }
}

Reference

HTTP	Code	Meaning	What to do
400	`invalid_request`	The request was malformed or missing required parameters.	Validate inputs against the OpenAPI spec.
400	`invalid_grant`	Authorization code, refresh token, or credentials are invalid or expired.	Restart the OAuth flow from /oauth/authorize.
400	`unsupported_grant_type`	grant_type is not one of authorization_code, refresh_token, client_credentials.	Send a supported grant_type.
400	`invalid_scope`	Requested scope is unknown or not allowed for this client.	Drop the rejected scope or have it added to the client.
401	`unauthorized`	Missing Bearer token or client credentials.	Attach Authorization: Bearer … or HTTP Basic auth.
401	`invalid_client`	Client credentials are wrong or the client is inactive.	Re-issue client_secret from the partner portal.
401	`invalid_token`	Access token is malformed, revoked, or expired.	Refresh the access token, or re-authorize.
403	`insufficient_scope`	Token is valid but missing a required scope.	Re-authorize with the additional scope listed in the error message.
403	`forbidden`	Authenticated, but not permitted (wrong account_type, no partner role, sandbox-only resource).	Check the token kind matches the endpoint.
404	`not_found`	The resource does not exist or is not visible to this token.	Confirm the ID and that the token's user owns the resource.
409	`conflict`	Resource state prevents the operation (e.g. already revoked).	Re-read the resource and adjust.
422	`validation_failed`	Schema-valid request but business rules rejected it.	Inspect the message for the specific field.
429	`rate_limited`	Too many requests from this client or IP.	Back off using the Retry-After header.
500	`internal_error`	Unexpected server error. Logged and alerted on our side.	Retry with exponential backoff; contact support if persistent.