Error Handling

Understand API error responses and recommended handling.

Error Handling

In a nutshell

API errors use the same top-level response envelope as successful responses, with status set to error.

Error shape

{
  "status": "error",
  "message": "Invalid api key",
  "data": null
}

Common status codes

Status	Meaning
400	Invalid request body or query parameters.
401	Missing or invalid API key.
404	Resource not found.
409	Conflict, such as duplicate tenant or customer.
500	Unexpected server error.

Examples

{
  "status": "error",
  "message": "Plan not found",
  "data": null
}

{
  "status": "error",
  "message": "A customer with this email already exists",
  "data": null
}

Handling guidance

• Treat non-2xx responses as failed requests.
• Surface validation messages in logs or dashboards.
• Retry network errors with care.
• Do not retry payment failures blindly.