Errors

The API uses standard HTTP status codes and returns consistent error responses. All errors follow the same response format.

Error Response Format

{
  "success": false,
  "error": "Description of what went wrong",
  "code": "ERROR_CODE"
}

Error Codes

HTTP Status	Code	Description
`400`	`BAD_REQUEST`	The request body is invalid or missing required fields.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`403`	`FORBIDDEN`	The API key does not have permission for this resource.
`403`	`QUOTA_EXCEEDED`	Monthly request quota has been exceeded. Upgrade your plan or wait for the next billing period.
`404`	`NOT_FOUND`	The requested resource does not exist.
`429`	`RATE_LIMITED`	Too many requests. Wait for the rate limit window to reset.
`500`	`INTERNAL_ERROR`	An unexpected server error occurred. Contact support if this persists.

Handling Errors

Always check the successfield in the response. If it's false, read the error message and code field to determine how to handle it.

const response = await fetch("/api/v1/example", {
  method: "POST",
  headers: {
    "x-api-key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "test" }),
});

const data = await response.json();

if (!data.success) {
  switch (data.code) {
    case "RATE_LIMITED":
      // Wait and retry
      break;
    case "QUOTA_EXCEEDED":
      // Upgrade plan
      break;
    case "UNAUTHORIZED":
      // Check API key
      break;
    default:
      console.error(data.error);
  }
}

Rate Limit Errors

When you exceed the rate limit, you'll receive a 429 response. Check the X-RateLimit-Reset header for when you can retry.