Error Codes

Every non-2xx response uses the same error shape, regardless of which endpoint or market you're calling.

HTTP status codes

Range	Meaning
`2xx`	Success
`4xx`	Client error. Review the request before retrying
`5xx`	Server error, safe to retry with backoff

Code	Meaning
`200`	OK, request succeeded
`400`	Bad Request, missing or invalid parameters
`401`	Unauthenticated, missing, expired, or invalid access token
`403`	Permission Denied, token is valid but lacks access to this resource
`404`	Not Found, the resource doesn't exist
`409`	Already Exists, a conflicting resource already exists
`5xx`	Internal / Unavailable. A platform-side issue; retry after a short wait

{
  "code": "not_found",
  "message": "consent not found",
  "details": {}
}

Field	Type	Meaning
`code`	`String`	Machine-readable error code, safe to branch on in code
`message`	`String`	Human-readable description for logs and debugging
`details`	`Object`	Optional structured context about the failure

`code`	Typical cause
`invalid_argument`	Request body or query parameter failed validation
`not_found`	The requested resource doesn't exist for your tenant
`already_exists`	A resource with the same unique identifier already exists
`permission_denied`	Your token doesn't have access to this resource
`unauthenticated`	Missing or expired access token, re-authenticate
`failed_precondition`	The request is valid but the resource isn't in a state that allows it (e.g. consent not yet authorized)
`resource_exhausted`	You've sent too many requests. Wait a moment, then retry
`unavailable`	The platform or a provider is temporarily unavailable. Retry shortly
`internal`	Unexpected server-side error, contact support with the request details

Branch on code, not message

message is for humans and may change. Always branch your error handling on code, never on the text of message.

Key takeaways

Continue learning

Data Types

Field formats used in success responses.

API Reference

Per-endpoint request and response schemas.