Errors

Unsuccessful API operations return a structured error object with a stable machine-readable type.

Error model

Name
message
Type
string · required
Description
Human-readable description of the failure. Do not branch application logic on this value.
Name
type
Type
ErrorType · required
Description
Machine-readable error type. Use this value for programmatic handling.
Name
details
Type
string
Description
Additional context when it is available.

Error response

{
  "message": "Card not found.",
  "type": "NotFound",
  "details": "No card is available for the supplied ID."
}

Error types

Name
NotFound
Description
The requested resource does not exist or is not available to your organization.
Name
InvalidRequest
Description
The request path, parameters, headers, or body are invalid.
Name
InternalError
Description
An unexpected server error occurred.
Name
Unauthorized
Description
Authentication failed or the token lacks access.

Handling errors

Use the HTTP status to determine the broad outcome and type for specific handling.
Correct authentication and validation failures before retrying.
Retry transient server failures with exponential backoff and a maximum attempt count.
Log only the status, error type, and a safe correlation value; do not log credentials or sensitive payload data.