Errors

Understand error responses, http status codes, and how to handle errors in Sandbox APIs.

When a request fails, Sandbox APIs return an error response with details about what went wrong.

Error response format

All error responses follow this structure:

{
  "code": 401,
  "message": "Unauthorized",
  "timestamp": 1687602744185,
  "transaction_id": "2230d738-2ef4-4821-a510-cb7fa51d19d8"
}

code · number

http status code indicating the error type

message · string

Human-readable description of the error

timestamp · number

Unix timestamp (in milliseconds) of when the error occurred

transaction_id · string

Unique identifier for tracking the request—include this when contacting support

http status codes

The following table lists common status codes and their meanings:

Status code	Description	How to resolve
2XX	Success	Request completed successfully
400 Bad Request	Missing or invalid required fields	Check request body against API documentation
401 Unauthorized	Invalid API key or secret	Verify your API credentials
403 Forbidden	Access denied	Check token validity, permissions, credits, or quota
404 Not Found	Invalid endpoint url	Verify the API endpoint path
422 Unprocessable Entity	Invalid field values or format	Validate field values against schema
429 Too Many Requests	Rate limit exceeded	Reduce request frequency or wait before retrying
500 Internal Server Error	Server-side issue	Retry the request; contact support if persistent
503 Service Unavailable	Source system unavailable	Retry later
504 Gateway Timeout	Request timed out	Retry the request

Common 403 error reasons

A 403 Forbidden response can occur for several reasons:

• Invalid access token
• Expired access token
• Insufficient permissions for the requested resource
• Insufficient wallet credits
• Usage quota exhausted
• Access revoked

Include the transaction_id from the error response when contacting support for faster resolution.