Errors and retries

The error envelope, the full list of answers and what to do about each.

Markdown

Envelope

{ "message": "MISSING_CLIENT_ID", "details": [] }

message identifies the error, and details is usually empty. When a flow refuses a request, for example an invalid image, the answer keeps this envelope with the reason in message and details. See Refusals.

Reference

Status	message	Endpoint	Retry?
400	INVALID_REQUEST	create	No. Fix the request
400	REQUEST_TOO_LARGE	create	No. Body over 2 MiB
400	MISSING_<FIELD> / INVALID_<FIELD>	create	No. <FIELD> is the field in upper snake case, for example MISSING_CREDENTIAL_VALUE
401	Empty ("")	create, selfie	No. Unico refused the access key. Check HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	create	No. Another process has that correlationId. Use a new one
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	create	No. Use a catalog code
4xx	The flow's message	create	No. The process is stored as failed
404	PROCESS_NOT_FOUND	get, selfie	No
404	SELFIE_NOT_FOUND	selfie	No. The process has no selfie available
4xx	The refusal message	selfie	No
503	DATABASE_UNAVAILABLE	all	Create: see below. Get and selfie: yes
502	UPSTREAM_UNAVAILABLE	all	Create: see below. Get and selfie: yes
500	INTERNAL	all	Create: see below

Retrying a create

Every accepted create starts a new process with a new id, and each correlationId can be used once: one already used, by a process in any state, is refused with 409 CORRELATION_ID_ALREADY_USED.

• 400, 409, 422 and other refusals: correct the request before sending it again.
• 503 DATABASE_UNAVAILABLE: nothing was stored or processed. Retry with the same correlationId.
• 502 and 500: the request was not confirmed. Do not retry automatically. To try again, send a new create with a new correlationId.

Recommended approach for your back-end:

1. Record each attempt before calling Human Plugin, keyed by its correlationId.
2. On 502 or 500, decide by your business rule whether to start a new attempt.
3. Keep related attempts linked in your records.

Retrying a read

GET, for a process or its selfie, is safe to retry. Use backoff, and stop on 404.

Rate limits

Human Plugin has no built-in rate limiter. Apply limits at your gateway if you need them.