Errors & status codes - Pexafy

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

Status	Meaning
`200` / `201`	Success.
`400`	Bad request — a parameter is missing or invalid.
`401`	Authentication failed — missing or invalid `x-api-key`.
`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 a rate limit. Slow down and retry.
`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.
`PHOTO_ALREADY_IN_COLLECTION`	409	The photo is already in that collection.
`RATE_LIMITED`	429	You exceeded the request rate limit.
`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.