Skip to main content
The 9Pic API uses standard HTTP status codes. Endpoint pages list which subset of these codes apply to that endpoint, and link here for the full description.

Error Envelope

Every error response uses the same three-key envelope as success responses, with responseType: "error" and data: null. The HTTP status code carries the error type; the message is a short human-readable description (safe to log, not stable enough to branch on).
422 Unprocessable Entity errors (request validation failures) flatten Pydantic field errors into a single message string of the form field.path: error description; field.path: error description. The HTTP status remains 422.

Status Codes

400 — Bad Request

Returned when the request itself is malformed. Common causes:
  • The uploaded selfie file is empty (multipart endpoints).
  • A video name search is shorter than 2 characters (“Type at least 2 characters.”).
  • request_id was provided but is not a valid UUID.
  • A handler-level check fails, such as an analytics date that is not YYYY-MM-DD.
  • Both X-API-Key and Authorization: Bearer were sent. Send exactly one.
A 400 means no billable work happened. Fix the request and resend it.

401 — Unauthorized

Returned when the request carries no credentials (the message is API Key is missing). Add the X-API-Key header and retry. See Authentication. For an OAuth access token, 401 means the token itself was rejected. The response includes a WWW-Authenticate: Bearer error="invalid_token" header and one of these messages:

403 — Forbidden

Returned for any of the following:
  • The API key is unknown, inactive, or has been deleted.
  • The organisation’s plan doesn’t include API keys (Pay As You Go or Pro). The message is “Your plan doesn’t include Developer API keys. It’s available on the Business plan.”
  • The org_id in the URL does not belong to the API key.
  • The event_id in the URL does not belong to the org_id.
  • The request originated from a host that is not on the allowlist (see Host Validation).
  • An OAuth token was used and:
    • no 9Pic account is linked to the sign-in, or the linked account is inactive;
    • the endpoint does not accept OAuth (This endpoint is not available to OAuth clients);
    • the token lacks the endpoint’s scope (Missing required scope: events:read, with a WWW-Authenticate: Bearer error="insufficient_scope" header);
    • the user is not a member of org_id or has not accepted the invitation (You do not have access to this organiser).
  • An X-API-Key was sent to an OAuth-only endpoint such as Account (This endpoint requires OAuth sign-in).
  • The endpoint requires an event-level feature flag (bib_search, selfie_search, timeline_search, video_search, video_selfie_search, video_bib_search) that is currently false for this event, or original-photo storage is off for Download Original Photos. Check the flags from Event Details before calling search endpoints.
A 403 will not become a 200 by retrying. Fix the underlying configuration first.

404 — Not Found

Returned when:
  • The event does not exist or its memories configuration is missing.
  • A request_id-scoped GET is called with an unknown UUID. This typically means no POST has been made for that UUID, or the search record was rotated out.
  • A video search is not available for the event’s search mode: while an event is set to video name search, selfie and bib video searches (and their results) answer 404 with “This search isn’t available for this event.”, and POST /video-clipping/search-by-name answers it when the event is not. See Video Clipping Search.
  • A BIB number does not exist for the event. (Some endpoints return a 200 with an empty images[] array instead — see the endpoint page for which behaviour applies.)

422 — Unprocessable Entity

Returned when the request body or query parameters fail Pydantic schema validation. Common causes:
  • Unknown value for an enum field (for example, method: "qr" on Download Original Photos, which only accepts "bib", "selfie", "image_id", or "image_ids").
  • Path or query parameters out of range (for example, page=0 or page_size above the maximum).
  • A missing or malformed JSON body on a POST endpoint that requires one.
  • A required field is missing from the JSON body.
  • A field is the wrong type (for example, identifier sent as a number instead of a string).
The message flattens all per-field errors into a single string. Fix the request and resend.

429 — Too Many Requests

Returned when the platform rate limit kicks in. The 9Pic API applies a sustained-rate limit and a burst capacity applied across the entire /api/v1/ext/... surface — every client, every key, and every endpoint share the same token bucket.
Exact rate and burst limits are tuned over time and are not published here. Contact support at hello@9pic.ai if you need the current numbers or want them raised for a specific event or campaign.
Unlike other errors, 429 responses are returned by the platform’s rate limiter before the request reaches the application layer. The body therefore does not match the unified { responseType, message, data } envelope. Expect a minimal payload such as:
Recommended client behaviour:
  • Treat 429 as transient and always retryable.
  • Use exponential backoff with jitter (for example, start at 500 ms, double up to a cap of 30 s, add ±25% jitter).
  • Reuse the same request_id on selfie-driven endpoints. A completed search returns its stored result, so you do not pay for the same search twice. After a failed or empty FaceFind search, start a fresh search with a new request_id — see request_id idempotency.
  • If you sustain bursts above the platform limit (for example, opening the search to large simultaneous audiences), reach out to support so we can review the throttle profile for your integration.

500 — Internal Server Error

Returned when the API could not record the request or start an async job. Examples:
  • Database write failed before the request could be persisted.
  • An async pipeline (for example, video clipping) could not be enqueued.
For video clipping, when the async job itself fails after the POST has been accepted, the GET endpoint will still return 200 with data.status: "failed" and data.error: "<reason>". The selfie record is marked failed, and a fresh POST is the safest retry path. See retry guidance.

Retry Guidance

Selfie-driven endpoints are designed to be retried with the same request_id. A completed search returns its stored result, so you do not pay twice for the same search. A request_id keeps its first stored result, so after a failure start a fresh search with a new request_id.

Endpoint-Specific Errors

Each endpoint page includes a short table listing only the codes that apply to that endpoint. Use this page for the canonical descriptions; use the endpoint page for which subset to expect.