---
title: Errors and retries
description: Every Human Plugin error response, which ones are safe to retry, and how to retry a create.
canonical: https://developer.unico.io/human-plugin/api-reference/errors-and-retries
locale: en
generated_by: markdown-export
---

# Errors and retries

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

## Envelope

```json
{ "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](/human-plugin/api-reference/create-process#flow-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.