# Errors

Every error, at every status, has the same JSON body:

```json
{
  "error": {
    "type": "invalid_request",
    "code": "age_below_18",
    "message": "listing.age must be 18 or over.",
    "field": "listing.age",
    "details": [
      { "field": "listing.age", "code": "age_below_18", "message": "listing.age must be 18 or over." }
    ],
    "doc_url": "https://docs.creator-guard.com/errors/#age_below_18",
    "request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
  }
}
```

| Member | Meaning |
|---|---|
| `type` | `invalid_request` (400, 404, 405, 409, 410, 412, 413, 415, 422), `authentication` (401), `permission` (403), `rate_limit` (429), `api_error` (5xx). |
| `code` | Stable and machine-readable. **Branch on this.** An unknown code: act on the HTTP status. |
| `message` | For a developer reading a log. The wording may change; never parse it. |
| `doc_url` | This page, at the code's row. |
| `request_id` | Same as the `X-Request-Id` header. Quote it to [support](https://docs.creator-guard.com/support/). |
| `field` | The request field of the (first) problem, when there is one. |
| `details` | Every field problem of the request at once: `[{field, code, message}]`. |

Some codes add one more member:

| Member | With |
|---|---|
| `lead` (`{id, creator_ref}`) | `duplicate_own_lead`: your existing lead. |
| `parameter` | `unknown_parameter` and `invalid_cursor`: the query parameter. |
| `agreement_type` | `terms_not_accepted`: the terms to accept (`referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`). |
| `scope` | `insufficient_scope`: the scope the key lacks. |
| `blockers` | `not_ready_for_review`: what is still missing. |
| `current_state` | `invalid_state`: the state that blocks the call (`current_version` instead on agreement accept). |
| `current_version` | `consent_text_outdated`: the text version that is current now — show her that text and ask again. |
| `limit` | `limit_reached`: the limit that is reached. |

## Order of checks

Request id → key (`401`, `403 account_not_active`) → test helpers with a live key (`404`) → IP allowlist → account type → scope → concurrency → rate limit → extract and upload limits → terms on writes → body (`413`, `415`, `400`) → `If-Match` → `Idempotency-Key` → the rules of the endpoint. Only the first failing check answers, except field validation, which reports every field in `details`.

## All codes

The creator endpoints (`/v1/creator/…`, [Creator API](https://docs.creator-guard.com/creator-api/)) answer with the same codes; `invalid_token` and `expired_token` are theirs. The OAuth endpoints on `app.creator-guard.com` answer in the OAuth format instead ([OAuth errors](https://docs.creator-guard.com/oauth/#errors-of-the-oauth-endpoints)).

| Status | Code | When | Retry |
|---|---|---|---|
| 400 | `invalid_json` | The body is not valid JSON. | no |
| 400 | `invalid_body` | The body is not a JSON object (for example an array). | no |
| 400 | `unknown_field` | A request field is not in the contract; `error.field` names it. | no |
| 400 | `unknown_parameter` | A query parameter this endpoint does not support; `error.parameter` names it. | no |
| 400 | `missing_field` | A required field is missing; `error.details` lists every problem. | no |
| 400 | `invalid_field` | A value has the wrong type, length, range or format. | no |
| 400 | `missing_contact` | `PATCH /v1/creator/profile` would leave her lead with neither `instagram_handle` nor `other_contact`. | no |
| 400 | `age_below_18` | `age` is below 18. | no |
| 400 | `consent_required` | `consent_confirmed` is not exactly `true`. | no |
| 400 | `invalid_cursor` | `starting_after` or `ending_before` is not one of your leads; `error.parameter` names it. | no |
| 401 | `missing_key` | No `Authorization: Bearer` header. | no |
| 401 | `invalid_key` | The key is unknown or revoked. | no |
| 401 | `expired_key` | The key is past its expiry date. | no |
| 401 | `invalid_token` | The creator access token is unknown, revoked, or from the other mode (her grant ended or was revoked: send her through the authorize flow again). | refresh |
| 401 | `expired_token` | The creator access token is past its hour: refresh it at `/oauth/token`. | refresh |
| 403 | `account_not_active` | The account is pending approval or disabled. With a creator access token: the account that owns the OAuth app (her grant stays and works again once the account is approved). | no |
| 403 | `terms_not_accepted` | A write needs the account's terms — and with a live key the API Terms (`api_terms`) and the data protection addendum (`api_dpa`); `error.agreement_type` names one at a time (the API Terms first), so accept and retry until the write goes through. | after accepting |
| 403 | `insufficient_scope` | The key lacks the scope in `error.scope`. | no |
| 403 | `wrong_account_type` | The endpoint is not for this account type. | no |
| 403 | `ip_not_allowed` | The key has an IP allowlist that does not contain the caller. | no |
| 403 | `mfa_required` | Portal only: key, webhook and payout changes need a second factor. API keys never get it. | after sign-in |
| 403 | `referrer_app_not_allowed` | Creator token of an OAuth app owned by the account that referred her: her consent, 18+ confirmation and creator terms are given only on Creator Guard (consent link or creator portal). Withdrawing consent is never refused. | no |
| 404 | `not_found` | Unknown path or id, or a resource of another account. | no |
| 405 | `method_not_allowed` | The path exists, the HTTP method does not. | no |
| 409 | `duplicate_own_lead` | Your lead with this Instagram handle is past `draft`; `error.lead` names it. | no |
| 409 | `duplicate_other_referrer` | Another account already submitted this Instagram handle (create, or a `PATCH` of `instagram_handle`). | no |
| 409 | `lead_locked` | Lead fields can no longer change (the lead left `draft`). | no |
| 409 | `listing_locked` | The listing is live; its fields and fee can no longer change. | no |
| 409 | `photos_locked` | The listing is live; its photos can no longer change (partner and creator endpoints alike). | no |
| 409 | `invalid_state` | Not allowed in the current state; `error.current_state` names it (`error.current_version` on agreement accept). | no |
| 409 | `offer_taken` | Accepting an offer: another agency accepted her first. | no |
| 409 | `offer_expired` | Accepting or declining an offer whose deadline passed. | no |
| 409 | `listing_unavailable` | Accepting an offer whose listing was pulled or that we retracted. | no |
| 409 | `payment_pending` | The step needs a paid reservation (offer progress, the creator's contact, a warranty claim). | later |
| 409 | `deal_paid` | Marking an offer lost after the placement fee was received. A paid deal ends only through a warranty claim or Creator Guard. | no |
| 409 | `undo_window_passed` | Undoing an accept after `undo_until`. | no |
| 409 | `claim_exists` | A second warranty claim on the same reservation. | no |
| 409 | `warranty_expired` | A warranty claim after the warranty ended. | no |
| 409 | `external_id_taken` | `external_id` is used by another of your leads. | no |
| 409 | `consent_text_outdated` | Granting consent, the 18+ confirmation or accepting the creator terms with a text version that is not the current one; `error.current_version` names it. Show her the current text (`GET /v1/creator/consent-text`) and ask again. A withdrawal never fails for this reason. | after refetch |
| 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` is still running. | yes |
| 409 | `limit_reached` | A limit of the account is reached (10 active keys or 10 webhook endpoints per mode, 20 photos per lead, 1,000 open deliveries per endpoint on replay); `error.limit` is the number. | no |
| 410 | `version_sunset` | A retired major version (not used in v1 yet). | no |
| 412 | `precondition_failed` | `If-Match` is not the current `ETag`. | after refetch |
| 413 | `payload_too_large` | The body is larger than 1 MB. | no |
| 415 | `unsupported_media_type` | The body is not `application/json`. | no |
| 422 | `not_ready_for_review` | Blockers remain; `error.blockers` lists them. | after fixing |
| 422 | `idempotency_key_reused` | The same `Idempotency-Key` with a different body. | no |
| 422 | `image_unreadable` | The uploaded file is not a readable JPEG, PNG or WebP image. | no |
| 429 | `rate_limited` | A rate limit is used up; wait `Retry-After` seconds. | yes |
| 429 | `concurrency_limited` | More than 25 requests of this key are in flight. | yes, slower |
| 429 | `duplicate_limit_reached` | The daily budget of answers about other accounts' creators is used up. | after Retry-After |
| 500 | `internal_error` | Unexpected error on our side; quote `request_id`. | yes |
| 502 | `upstream_failed` | A service we depend on failed (text extraction, or the DNS lookup of a webhook URL); nothing was stored. | yes |
| 503 | `not_configured` | A setting is missing on our side (for example text extraction), or test mode is briefly unavailable. | no |

## 5xx and gateway errors

`500 internal_error` never contains database details. Retry with the same `Idempotency-Key`: a `5xx` answer is never stored, so the retry runs again. A `502` or `504` without a JSON body comes from the gateway during a restart; retry after a few seconds.
