> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authflame.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error responses and HTTP status codes

> How the AuthFlame API signals failure: HTTP status codes, error envelope shape, and how to handle each category of error in your integration.

AuthFlame uses conventional HTTP status codes and returns a JSON error envelope on failure. Handle errors defensively: never block signups because AuthFlame is briefly unreachable, but do fail closed on clear authentication problems.

## Status codes

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `200`  | Success. The response body contains the check result.                 |
| `400`  | Bad request. The body is malformed or missing a required field.       |
| `401`  | Unauthorized. The API key is missing, malformed, or revoked.          |
| `403`  | Forbidden. The API key is valid but not allowed to use this endpoint. |
| `422`  | Unprocessable input, for example an email that cannot be parsed.      |
| `429`  | Rate limited. Retry after a short backoff.                            |
| `5xx`  | AuthFlame is temporarily unavailable. Retry with exponential backoff. |

## Error envelope

Errors return a JSON body with a stable shape:

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}
```

* **`error.code`**: a short, machine-readable string you can branch on.
* **`error.message`**: a human-readable description. Do not surface this directly to end users.

## Handling errors in your signup flow

<Steps>
  <Step title="Distinguish user errors from platform errors">
    Treat `4xx` responses as problems with the request (fix your integration or the input). Treat `5xx` and network errors as transient AuthFlame issues.
  </Step>

  <Step title="Fail closed on auth errors">
    A `401` or `403` means your integration is misconfigured. Log the incident and stop sending traffic with that key until it is fixed.
  </Step>

  <Step title="Fail open on transient errors">
    For `5xx` responses and timeouts, decide up front whether to allow the signup, queue it for later review, or fall back to a lightweight local check. Blocking every signup during an outage is usually the wrong tradeoff.
  </Step>

  <Step title="Back off on 429">
    Respect `429` responses with exponential backoff. Bursting signups in a loop will keep you rate limited longer.
  </Step>
</Steps>