Errors

Errors use a stable JSON envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed."
  }
}

Common public status codes:

400 bad request, such as an invalid cursor
401 missing or invalid API key, Firebase ID token, or App Check token
402 billing disabled, paid-plan upgrade required, or monthly plan allowance exhausted
403 valid credential without the required scope
404 job not found
409 idempotency conflict or invalid cancellation state
422 request validation failed
429 request exceeded an operational rate limit or anonymous scan allowance

Authentication failure:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

Scope failure:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope."
  }
}

Billing disabled:

{
  "error": {
    "code": "billing_disabled",
    "message": "Billing is disabled for this account."
  }
}

Invalid web credential:

{
  "error": {
    "code": "invalid_public_credential",
    "message": "Missing or invalid public credential."
  }
}

Rate limited:

{
  "error": {
    "code": "rate_limited",
    "message": "The request exceeded the rate limit."
  }
}

Anonymous scan allowance exceeded:

{
  "error": {
    "code": "anonymous_quota_exceeded",
    "message": "Anonymous scan quota exceeded for today."
  }
}

Monthly plan allowance exhausted:

{
  "error": {
    "code": "allowance_exhausted",
    "message": "Monthly scan word allowance exhausted.",
    "pool": "scan",
    "docs": "https://draftfilter.com/docs/rate-limits"
  }
}

Paid-plan upgrade required:

{
  "error": {
    "code": "upgrade_required",
    "message": "Humanizer requires a paid plan."
  }
}

Idempotency conflict:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key was already used for a different score request."
  }
}

Do not parse messages for control flow. Branch on HTTP status and error.code.