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 not valid JSON or is missing a required field.
`401`	Unauthorized. The API key is missing, malformed, or revoked.
`402`	Payment required. Your team’s subscription is not active.
`405`	Method not allowed. The endpoint only accepts `POST`.
`422`	Unprocessable input, for example an email that cannot be parsed.
`429`	Too many requests. You hit your per-second rate limit or your monthly quota. Check `error.code` to tell them apart.
`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 provided API key is invalid or 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.
error.field: present on some 400 and 422 errors. The name of the request field that caused the problem, for example email.

Error codes

Status	Code	Meaning
`400`	`invalid_json`	The request body is not valid JSON.
`400`	`missing_field`	A required field, such as `email`, is missing or empty.
`401`	`missing_or_malformed_api_key`	The `Authorization` header is missing or is not a valid Bearer API key.
`401`	`invalid_api_key`	The API key is invalid or has been revoked.
`402`	`subscription_inactive`	The team’s subscription is not active. Update your billing details.
`405`	`method_not_allowed`	The endpoint only accepts `POST`.
`422`	`invalid_email_format`	The submitted string cannot be parsed as an email address.
`429`	`rate_limited`	You exceeded your plan’s requests-per-second limit. A `Retry-After` header tells you how many seconds to wait.
`429`	`quota_exceeded`	You used your monthly quota of checks. It resets on the first of the month, or when you upgrade your plan.
`500`	`internal_error`	An unexpected error occurred on our side. Retry shortly.

See Limits for the quota and rate limit on each plan.

Distinguish request errors, account errors, and platform errors

Treat 400, 405, and 422 responses as problems with the request (fix your integration or the input). Treat 401 and 402 as problems with your account. Treat 429 as a limit, and 5xx and network errors as transient AuthFlame issues.

Fail closed on auth errors

A 401 means your integration is misconfigured. Log the incident and stop sending traffic with that key until it is fixed.

Act on billing errors

A 402 means checks will keep failing until your subscription is active again. Alert your team and fix billing, and decide up front how signups are handled in the meantime.

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.

Handle each kind of 429 differently

For rate_limited, wait for the number of seconds in the Retry-After header and retry, with exponential backoff if it persists. Bursting signups in a loop will keep you rate limited longer. For quota_exceeded, do not retry: the quota will not recover until it resets, so alert your team, consider upgrading, and apply the same fallback you use for transient errors.

Overview

Endpoints

Error responses and HTTP status codes

Status codes

Error envelope

Error codes

​Status codes

​Error envelope

​Error codes

​Handling errors in your signup flow

Status codes

Error envelope

Error codes

Handling errors in your signup flow