Error Envelope
Every error response uses the same three-key envelope as success responses, withresponseType: "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_idwas 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-KeyandAuthorization: Bearerwere sent. Send exactly one.
401 — Unauthorized
Returned when the request carries no credentials (the message isAPI 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_idin the URL does not belong to the API key. - The
event_idin the URL does not belong to theorg_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 aWWW-Authenticate: Bearer error="insufficient_scope"header); - the user is not a member of
org_idor has not accepted the invitation (You do not have access to this organiser).
- An
X-API-Keywas 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 currentlyfalsefor this event, or original-photo storage is off for Download Original Photos. Check the flags from Event Details before calling search endpoints.
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 noPOSThas 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
404with “This search isn’t available for this event.”, andPOST /video-clipping/search-by-nameanswers it when the event is not. See Video Clipping Search. - A BIB number does not exist for the event. (Some endpoints return a
200with an emptyimages[]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=0orpage_sizeabove 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,
identifiersent as a number instead of a string).
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.
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:
- Treat
429as 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_idon 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 newrequest_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.
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.

