Errors & status codes

Error format

Errors nest a consistent envelope under detail, with a machine-readable error code and a human-readable message:

{
  "detail": {
    "error": "NOT_FOUND",
    "message": "Submission not found."
  }
}

Two cases shape detail differently:

422 validation errors: detail is a list of issues, each naming the offending field in loc with a msg and a type.
502 and 503 from search: detail is a plain string.

Status codes

Status	Code	Meaning
200	(none)	Success. The result endpoint may return a partial body while a job runs.
202	(none)	The submission was accepted for asynchronous processing.
401	`UNAUTHORIZED`	The API key is missing, invalid, or expired.
402	`INSUFFICIENT_CREDITS`	The account doesn’t have enough credits to run the request.
403	`FORBIDDEN`	The key is valid but is not allowed to call this endpoint.
404	`NOT_FOUND`	The resource was not found or isn’t accessible with these credentials.
409	`NOT_READY`	The result isn’t ready yet. Keep polling.
422	(validation)	The request payload failed validation. `detail` lists the issues.
424	`BRAND_ADHERENCE_FAILED`	A brand-adherence job failed permanently. No verdict will be produced, so stop polling.
500		An unexpected server error occurred. The body is plain text.
502		A search failed. The credit is refunded.
503		Search is at capacity. Retry after the `Retry-After` header.

Polling and `409 NOT_READY`

409 NOT_READY is expected, not a failure: it means no checkpoint has landed yet for a running job. Retry GET /design/submissions/{id}/result (or GET /judge/brand-adherence/{job_id}/result for adherence jobs) shortly. Once a checkpoint lands you’ll get a 200 (possibly with a partial body) and you keep polling until status is completed or failed. The adherence result endpoint adds one terminal case: a job whose status is failed returns 424 BRAND_ADHERENCE_FAILED. Unlike 409, that state never resolves, so stop polling and read the job’s error for the reason.

Authentication errors

A request your key is not allowed to make returns 403 FORBIDDEN.
An expired or invalid key returns 401 UNAUTHORIZED.

See Authentication for how expiration works.

Insufficient credits

When credit metering is enabled for your account, credit-metered endpoints return 402 INSUFFICIENT_CREDITS if your balance is too low to cover the request. Creating a submission (POST /design/submissions) and running a search both cost credits; the charge is refunded automatically if the request fails. The response includes your current balance and the required amount:

{
  "detail": {
    "error": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this request.",
    "balance": 0,
    "required": 1
  }
}

Getting Started

Use cases

Brand extractor

Brand search

Brand adherence verifier

Integrate Agents

Reference

Error format

Status codes

Polling and `409 NOT_READY`

Authentication errors

Insufficient credits

​Error format

​Status codes

​Polling and 409 NOT_READY

​Authentication errors

​Insufficient credits

Error format

Status codes

Polling and `409 NOT_READY`

Authentication errors

Insufficient credits