/v1 с ошибкой представлен в формате application/problem+json (RFC 9457) с фиксированным набором полей:
code, а не на detail: code — это стабильный машинный контракт, а detail предназначено для чтения человеком и может измениться. Поле param присутствует, если ошибка связана с конкретным параметром запроса. При обращении в службу поддержки укажите request_id.
Коды ошибок
Набор кодов является закрытым: добавление новых кодов — это изменение публичного контракта, о котором сообщается в журнале изменений API. Ответ
retryable: true означает, что условие может перестать действовать, но не доказывает, что операция записи не имела последствий. Повторяйте запросы на чтение с ограниченным числом попыток и ограниченным временем, используя экспоненциальную задержку и джиттер. Учитывайте Retry-After, если он присутствует, в том числе в повторяемом ответе 409 или 429.
Для операций изменения следуйте документированному контракту идемпотентности и восстановления для соответствующей операции. Если это поддерживается, сохраняйте исходный ключ и исходный запрос. Не создавайте новый ключ после тайм-аута или 5xx: это может привести к повторному выполнению уже успешной записи. Заголовок Idempotency-Key не обеспечивает защиты для операции, которая его не поддерживает.