Skip to main content

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

StatusMeaning
400Invalid request body or query parameters.
401Missing or invalid API key.
404Resource not found.
409Conflict, such as duplicate tenant or customer.
500Unexpected 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.