Error Handling

Response Codes

We use standard HTTP status codes to indicate the outcome of API requests. Codes in the 2xx range means success, 4xx errors indicate client-side issues (e.g., invalid requests or authorization failures), and 5xx errors indicate server-side problems.

Refer to the table below for details:

Status Code	Error Type	When It Happens	What You Should Do
200	OK	The request was successful.	No action needed.
400	Bad Request	The request is missing required parameters or has invalid values.	Check the request format, required fields, and value types.
401	Unauthorized	The request lacks valid authentication credentials.	Make sure you're including a valid API key or token in the request header. See the Authentication page.
403	Forbidden	You're authenticated but don’t have access to the requested resource.	Confirm your API key has the correct permissions.
404	Not Found	The requested endpoint or resource doesn't exist.	Verify the URL and endpoint name.
405	Method Not Allowed	The HTTP method used is not supported for the endpoint.	Use a supported HTTP method (e.g., GET, POST).
422	Unprocessable Entity	The request is valid, but can't be processed due to semantic errors.	Review the request payload for logical issues or unsupported values.
429	Too Many Requests	You've exceeded the allowed request rate or quota.	Wait and retry. See the Rate Limits page for reference.
500	Internal Server Error	The server encountered an unexpected error.	Retry after a short delay. Contact support if it persists.
503	Service Unavailable	The server is temporarily overloaded or under maintenance.	Retry later. Monitor the status page for service availability updates.

Sample Error Responses

When an error occurs, the API may return a JSON response with fields such as type, title, status, and sometimes additional details.

Below are examples of common error responses:

401 - Unauthorized

{
  "type": "unauthorized",
  "title": "Invalid Token",
  "status": 401
}

400 - Bad Request

{
  "timestamp": "string",
  "path": "/v2/solana/mainnet/delegator",
  "status": 400,
  "error": "[endTime should be in unix epoch seconds]"
}

404 - Not Found

{
  "type": "not-found",
  "title": "Not Found",
  "status": 404
}

429 - Too Many Requests

{
  "type": "too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Request rate limits have been exceeded. Try again after a few seconds."
}

500 - Internal Server Error

{
  "type": "internal-server-error",
  "title": "Internal Server Error",
  "status": 500
}