API

Errors

Stable codes you can switch on.

Every error uses the same shape. Branch on code, never on message.

json

{ "code": "INSUFFICIENT_CREDITS", "message": "Top up the account balance and retry.", "status": 402 }

Auth and routing

Code	HTTP	Meaning
`MISSING_API_KEY`	401	No `x-api-key` header
`INVALID_API_KEY`	401	Unknown or rotated-out key
`FORBIDDEN`	403	Key lacks access to the resource
`ROUTE_NOT_FOUND`	404	—

Code	HTTP	Meaning
`VALIDATION_FAILED`	400	Carries `details`
`FILE_TOO_LARGE`	413	Over 10 MB
`UNSUPPORTED_IMAGE_TYPE`	400	Not JPEG, PNG, WebP or HEIC
`CUSTOMER_IMAGE_REQUIRED`	400	No `person.image.source`
`PRODUCT_IMAGE_FETCH_FAILED`	400	Product image URL unreachable
`PRODUCT_NOT_FOUND`	404	Reference call for an expired product — fall back to inline upsert

These run before any inference spend and consume no credit.

Code	HTTP	Meaning
`NO_PERSON_DETECTED`	422	No person found in the photo
`MULTIPLE_PERSONS`	422	More than one person
`UNSUITABLE_POSE`	422	Framing or angle unusable
`IMAGE_QUALITY_TOO_LOW`	422	Blur or resolution below threshold
`CONTENT_POLICY`	422	Input failed moderation. Message is deliberately generic

Code	HTTP	Meaning
`INSUFFICIENT_CREDITS`	402	Top up and retry
`QUOTA_EXCEEDED`	402	Allowance exhausted
`RATE_LIMITED`	429	Retryable — back off
`PROVIDER_UNAVAILABLE`	503	No model cleared the quality gate. Retryable
`QUALITY_CHECK_FAILED`	502	Output failed validation on every candidate
`GENERATION_TIMEOUT`	504	Did not terminate in time

Failed generations are never billed. A credit is settled only when a generation reaches

COMPLETED.