Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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.
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).

StatusCodeWhenRetry
400invalid_jsonThe body is not valid JSON.no
400invalid_bodyThe body is not a JSON object (for example an array).no
400unknown_fieldA request field is not in the contract; error.field names it.no
400unknown_parameterA query parameter this endpoint does not support; error.parameter names it.no
400missing_fieldA required field is missing; error.details lists every problem.no
400invalid_fieldA value has the wrong type, length, range or format.no
400missing_contactPATCH /v1/creator/profile would leave her lead with neither instagram_handle nor other_contact.no
400age_below_18age is below 18.no
400invalid_cursorstarting_after or ending_before is not one of your leads; error.parameter names it.no
401missing_keyNo Authorization: Bearer header.no
401invalid_keyThe key is unknown or revoked.no
401expired_keyThe key is past its expiry date.no
401invalid_tokenThe 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
401expired_tokenThe creator access token is past its hour: refresh it at /oauth/token.refresh
403account_not_activeThe 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
403terms_not_acceptedA 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
403insufficient_scopeThe key lacks the scope in error.scope.no
403wrong_account_typeThe endpoint is not for this account type.no
403ip_not_allowedThe key has an IP allowlist that does not contain the caller.no
403mfa_requiredPortal only: key, webhook and payout changes need a second factor. API keys never get it.after sign-in
403referrer_app_not_allowedCreator 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
404not_foundUnknown path or id, or a resource of another account.no
405method_not_allowedThe path exists, the HTTP method does not.no
409duplicate_own_leadYour lead with this Instagram handle is past draft; error.lead names it.no
409duplicate_other_referrerAnother account already submitted this Instagram handle (create, or a PATCH of instagram_handle).no
409lead_lockedLead fields can no longer change (the lead left draft).no
409listing_lockedThe listing is live; its fields and fee can no longer change.no
409photos_lockedThe listing is live; its photos can no longer change (partner and creator endpoints alike).no
409invalid_stateNot allowed in the current state; error.current_state names it (error.current_version on agreement accept).no
409offer_takenAccepting an offer: another agency accepted her first.no
409offer_expiredAccepting or declining an offer whose deadline passed.no
409listing_unavailableAccepting an offer whose listing was pulled or that we retracted.no
409payment_pendingThe step needs a paid reservation (offer progress, the creator's contact, a warranty claim).later
409deal_paidMarking an offer lost after the placement fee was received. A paid deal ends only through a warranty claim or Creator Guard.no
409undo_window_passedUndoing an accept after undo_until.no
409claim_existsA second warranty claim on the same reservation.no
409warranty_expiredA warranty claim after the warranty ended.no
409external_id_takenexternal_id is used by another of your leads.no
409idempotency_in_progressThe first request with this Idempotency-Key is still running.yes
409limit_reachedA 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
410version_sunsetA retired major version (not used in v1 yet).no
412precondition_failedIf-Match is not the current ETag.after refetch
413payload_too_largeThe body is larger than 1 MB.no
415unsupported_media_typeThe body is not application/json.no
422not_ready_for_reviewBlockers remain; error.blockers lists them.after fixing
422idempotency_key_reusedThe same Idempotency-Key with a different body.no
422image_unreadableThe uploaded file is not a readable JPEG, PNG or WebP image.no
429rate_limitedA rate limit is used up; wait Retry-After seconds.yes
429concurrency_limitedMore than 25 requests of this key are in flight.yes, slower
429duplicate_limit_reachedThe daily budget of answers about other accounts' creators is used up.after Retry-After
500internal_errorUnexpected error on our side; quote request_id.yes
502upstream_failedA service we depend on failed (text extraction, or the DNS lookup of a webhook URL); nothing was stored.yes
503not_configuredA 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.