Errors
Every error, at every status, has the same JSON body:
{
"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. |
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) 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).
| 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.