success is false
and the error object is populated:
error.code (stable, machine-readable) rather than parsing error.message
(human-readable, may change). Quote meta.request_id when contacting support.
HTTP status codes
| Status | Meaning |
|---|---|
200 / 201 | Success. |
400 | Bad request — a parameter is missing or invalid. |
401 | Authentication failed — missing or invalid key. Send it in the x-api-key header or as Authorization: Bearer <key>, never in the URL. |
403 | Forbidden — your plan or account is not allowed to perform this action. |
404 | The resource (photo, collection, photographer) or route does not exist. |
409 | Conflict — the action clashes with the current state (e.g. duplicate). |
422 | Validation error — a parameter failed validation (type, range, required). |
429 | Too many requests — you hit the rate limit or the monthly quota; error.code says which. |
500 | Internal error — something went wrong on our side. |
504 | The search backend timed out — retry shortly. |
Error codes
error.code | Status | When it happens |
|---|---|---|
MISSING_PARAMS | 400 | A search was sent with no query and no filter. |
INVALID_PARAMS | 400 | Conflicting parameters (e.g. color_name and color_hex together). |
INVALID_ID | 400 | photo_id is not a valid UUID. |
VALIDATION_ERROR | 422 | A parameter failed validation (out of range, wrong type, required). The error.fields array lists each offending parameter. |
MISSING_IMAGE | 422 | Image search was called without an image file. |
INVALID_IMAGE | 422 | The uploaded file is not a supported image (JPEG, PNG, WebP, AVIF) or is too large. |
UNAUTHORIZED | 401 | The x-api-key header is missing or invalid. |
FORBIDDEN | 403 | Your account/plan cannot perform this action. |
PLAN_RESTRICTION | 403 | The requested field or feature is not in your plan. |
COLLECTIONS_LIMIT_REACHED | 403 | You reached the maximum number of collections for your plan. |
PHOTO_NOT_FOUND | 404 | No photo matches the given photo_id. |
NOT_FOUND | 404 | The collection, photographer or route does not exist. For a route, error.message names the one you probably meant (e.g. /api/v1/search/photos for /v1/search). |
PHOTO_ALREADY_IN_COLLECTION | 409 | The photo is already in that collection. |
RATE_LIMITED | 429 | You exceeded the request rate limit. |
QUOTA_EXCEEDED | 429 | You used your plan’s monthly requests. Resets on the 1st of the month at 00:00 UTC. |
SEARCH_TIMEOUT | 504 | The search backend did not respond in time — retry. |
INTERNAL_ERROR | 500 | Unexpected server error — retry, then contact support with the request_id. |
VALIDATION_ERROR responses include an extra error.fields array — one entry per invalid
parameter with its field, message and type — so you can show precise form errors.Warnings
A parameter the endpoint does not know is ignored, not refused — the request still succeeds. So that it does not go unnoticed, the response then carries ameta.warnings list
and an X-Pexafy-Warning header naming what was ignored and what to send instead:
warnings[].code | When it happens |
|---|---|
UNKNOWN_PARAMETER | The parameter is not read by this endpoint (a typo, or a name from another API). |
LIMIT_IS_TOTAL | limit was sent without per_page: limit caps the total across pages, per_page sets the page size. |
INVALID_PAGE | page is not a whole number from 1; the first page was returned. |
PAGE_IGNORED | Both page and cursor were sent; the cursor was used. |
QUERY_IGNORED | Both q and query were sent; q was used. |
QUERY_TOO_LONG | query is longer than 500 characters and was not used. |
meta.warnings is absent when there is nothing to report, so its presence alone tells you
to look at your parameters.
Rate limits and quotas
Two limits apply to every API key, both set by your plan — see Plans & limits for the figures:- a rate limit, in requests per minute. Past it you get
429RATE_LIMITEDwith aRetry-Afterheader (seconds): wait that long and retry. - a monthly quota, counted per account across all its keys. Past it you get
429QUOTA_EXCEEDEDand noRetry-After: retrying does not help until the quota resets on the 1st of the month (00:00 UTC), or until you move to a bigger plan.
| Header | Meaning |
|---|---|
X-Plan | Your plan. |
X-Quota-Limit | Requests included per month. |
X-Quota-Remaining | Requests left this month. |
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current minute. |
X-RateLimit-Reset | Unix timestamp (seconds) by which the per-minute window has reset. |
page or with
cursor (see Pagination). Reading your usage (/usage), the facets
(/facets/…) and your collections does not count against the monthly quota.