Error responses and HTTP status codes

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:

{
  "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.

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.

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.

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.

Back off on 429

Respect 429 responses with exponential backoff. Bursting signups in a loop will keep you rate limited longer.

Overview

Endpoints

Error responses and HTTP status codes

Status codes

Error envelope

​Status codes

​Error envelope

​Handling errors in your signup flow

Status codes

Error envelope

Handling errors in your signup flow