Every error uses the same envelope as successful responses — only success is false and the error object is populated:
{
  "success": false,
  "data": null,
  "meta": {
    "request_id": "b3f1c2e4-...",
    "took_ms": 2.9
  },
  "error": {
    "code": "MISSING_PARAMS",
    "message": "At least one criterion required: q, color_name, color_hex, orientation, source, license_type, photographer or after_date.",
    "request_id": "b3f1c2e4-..."
  }
}
Always branch on error.code (stable, machine-readable) rather than parsing error.message (human-readable, may change). Quote meta.request_id when contacting support.

HTTP status codes

StatusMeaning
200 / 201Success.
400Bad request — a parameter is missing or invalid.
401Authentication failed — missing or invalid key. Send it in the x-api-key header or as Authorization: Bearer <key>, never in the URL.
403Forbidden — your plan or account is not allowed to perform this action.
404The resource (photo, collection, photographer) or route does not exist.
409Conflict — the action clashes with the current state (e.g. duplicate).
422Validation error — a parameter failed validation (type, range, required).
429Too many requests — you hit the rate limit or the monthly quota; error.code says which.
500Internal error — something went wrong on our side.
504The search backend timed out — retry shortly.

Error codes

error.codeStatusWhen it happens
MISSING_PARAMS400A search was sent with no query and no filter.
INVALID_PARAMS400Conflicting parameters (e.g. color_name and color_hex together).
INVALID_ID400photo_id is not a valid UUID.
VALIDATION_ERROR422A parameter failed validation (out of range, wrong type, required). The error.fields array lists each offending parameter.
MISSING_IMAGE422Image search was called without an image file.
INVALID_IMAGE422The uploaded file is not a supported image (JPEG, PNG, WebP, AVIF) or is too large.
UNAUTHORIZED401The x-api-key header is missing or invalid.
FORBIDDEN403Your account/plan cannot perform this action.
PLAN_RESTRICTION403The requested field or feature is not in your plan.
COLLECTIONS_LIMIT_REACHED403You reached the maximum number of collections for your plan.
PHOTO_NOT_FOUND404No photo matches the given photo_id.
NOT_FOUND404The 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_COLLECTION409The photo is already in that collection.
RATE_LIMITED429You exceeded the request rate limit.
QUOTA_EXCEEDED429You used your plan’s monthly requests. Resets on the 1st of the month at 00:00 UTC.
SEARCH_TIMEOUT504The search backend did not respond in time — retry.
INTERNAL_ERROR500Unexpected 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 a meta.warnings list and an X-Pexafy-Warning header naming what was ignored and what to send instead:
{
  "success": true,
  "data": [ /* photos */ ],
  "meta": {
    "request_id": "b3f1c2e4-...",
    "took_ms": 41.7,
    "warnings": [
      {
        "code": "UNKNOWN_PARAMETER",
        "parameter": "page_size",
        "message": "`page_size` is not a parameter of this endpoint and was ignored. Use `per_page` (1–100, default 20) for the page size."
      }
    ]
  }
}
warnings[].codeWhen it happens
UNKNOWN_PARAMETERThe parameter is not read by this endpoint (a typo, or a name from another API).
LIMIT_IS_TOTALlimit was sent without per_page: limit caps the total across pages, per_page sets the page size.
INVALID_PAGEpage is not a whole number from 1; the first page was returned.
PAGE_IGNOREDBoth page and cursor were sent; the cursor was used.
QUERY_IGNOREDBoth q and query were sent; q was used.
QUERY_TOO_LONGquery 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 429 RATE_LIMITED with a Retry-After header (seconds): wait that long and retry.
  • a monthly quota, counted per account across all its keys. Past it you get 429 QUOTA_EXCEEDED and no Retry-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.
Every response tells you where you stand:
HeaderMeaning
X-PlanYour plan.
X-Quota-LimitRequests included per month.
X-Quota-RemainingRequests left this month.
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetUnix timestamp (seconds) by which the per-minute window has reset.
Each page of results counts as one request, whether you ask for it with page or with cursor (see Pagination). Reading your usage (/usage), the facets (/facets/…) and your collections does not count against the monthly quota.