Ошибки и повторные попытки

Формат ошибки, полный список ответов и что делать в каждом случае.

Markdown

Формат ошибки

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

message идентифицирует ошибку, а details обычно пуст. Когда поток отклоняет запрос, например из-за недопустимого изображения, ответ сохраняет этот формат, а причина указывается в message и details. См. Отказы.

Справочник

Статус	message	Эндпоинт	Повторять?
400	INVALID_REQUEST	create	Нет. Исправьте запрос
400	REQUEST_TOO_LARGE	create	Нет. Тело больше 2 MiB
400	MISSING_<FIELD> / INVALID_<FIELD>	create	Нет. <FIELD> — имя поля в верхнем регистре со змеиным написанием, например MISSING_CREDENTIAL_VALUE
401	Пусто ("")	create, selfie	Нет. Unico отклонил ключ доступа. Проверьте HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	create	Нет. У другого процесса уже есть такой correlationId. Используйте новый
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	create	Нет. Используйте код из каталога
4xx	message потока	create	Нет. Процесс сохраняется как завершившийся ошибкой
404	PROCESS_NOT_FOUND	get, selfie	Нет
404	SELFIE_NOT_FOUND	selfie	Нет. Для процесса нет доступного селфи
4xx	message отказа	selfie	Нет
503	DATABASE_UNAVAILABLE	все	Create: см. ниже. Get и selfie: да
502	UPSTREAM_UNAVAILABLE	все	Create: см. ниже. Get и selfie: да
500	INTERNAL	все	Create: см. ниже

Повтор создания процесса

Каждое принятое создание запускает новый процесс с новым id, а каждый correlationId можно использовать один раз: уже использованный процессом в любом состоянии отклоняется ответом 409 CORRELATION_ID_ALREADY_USED.

• 400, 409, 422 и прочие отказы: исправьте запрос, прежде чем отправлять его снова.
• 503 DATABASE_UNAVAILABLE: ничего не было сохранено или обработано. Повторите с тем же correlationId.
• 502 и 500: запрос не был подтверждён. Не повторяйте автоматически. Чтобы попробовать снова, отправьте новое создание с новым correlationId.

Рекомендуемый подход для вашего бэкенда:

1. Фиксируйте каждую попытку до вызова Human Plugin, используя её correlationId как ключ.
2. При 502 или 500 решайте по своему бизнес-правилу, начинать ли новую попытку.
3. Сохраняйте связь между родственными попытками в своих записях.

Повтор чтения

GET для процесса или его селфи можно безопасно повторять. Используйте экспоненциальную задержку и прекращайте при 404.

Ограничения частоты запросов

В Human Plugin нет встроенного ограничителя частоты запросов. При необходимости задайте лимиты на вашем шлюзе.