Справочник по кодам статуса HTTP

Коды ошибок

Справочник ошибок и ответов API

При выполнении некорректного запроса к системе наше API может вернуть код ошибки, в случае же верного запроса, API вернёт ответ. Вы, конечно, уже обрабатывали ответ сервера в ходе отладки своих виджетов или написании скриптов, взаимодействующих с нашей системой. Для Вашего удобства, мы решили систематизировать все возможные ответы и ошибки, отдаваемые нашей системой и разместить их на отдельной странице. Надеемся это облегчит и ускорит интеграцию Ваших проектов с amoCRM.

Ошибки при валидации данных

Если переданные данные не совпадают с теми, что доступны для сущности, запрос вернет HTTP-код 400 Bad Request и массив с параметрами, которые не подошли под условия.

Пример ошибки валидации данных

{
    "validation-errors": [
        {
            "request_id": "0",
            "errors": [
                {
                    "code": "NotSupportedChoice",
                    "path": "custom_fields_values. 0.field_id",
                    "detail": "The value you selected is not a valid choice."
                }
            ]
        }
    ],
    "title": "Bad Request",
    "type": "https://httpstatus.es/400",
    "status": 400,
    "detail": "Request validation failed"
}

Ответы при авторизации

Подробнее об авторизации читайте здесь

Код	HTTP код	Описание
110	401 Unauthorized	Общая ошибка авторизации. Неправильный логин или пароль.
111	401 Unauthorized	Возникает после нескольких неудачных попыток авторизации. В этом случае нужно авторизоваться в аккаунте через браузер, введя код капчи.
112	401 Unauthorized	Возникает, когда пользователь выключен в настройках аккаунта “Пользователи и права” или не состоит в аккаунте.
113	403 Forbidden	Доступ к данному аккаунту запрещён с Вашего IP адреса. Возникает, когда в настройках безопасности аккаунта включена фильтрация доступа к API по “белому списку IP адресов”.
101	401 Unauthorized	Возникает в случае запроса к несуществующему аккаунту (субдомену).

Ответы при работе с контактами

Подробнее о работе с контактами читайте здесь

Ответы при работе со сделками

Подробнее о работе со сделками читайте здесь

Ответы при работе с событиями

Подробнее о работе с событиями читайте здесь

Ответы при работе с задачами

Подробнее о работе с задачами читайте здесь

Код	Описание
231	Обновление задач: задачи не найдены
233	Добавление событий: по данному ID элемента не найдены некоторые контакты
234	Добавление событий: по данному ID элемента не найдены некоторые сделки
235	Добавление задач: не указан тип элемента
236	Добавление задач: по данному ID элемента не найдены некоторые контакты
237	Добавление задач: по данному ID элемента не найдены некоторые сделки
244	Добавление сделок: нет прав.

Ответы при работе со списками

Подробнее о работе со списками читайте здесь

Ответы при работе с элементами каталога

Подробнее о работе с элементами каталога читайте здесь

Код	Описание
203	Добавление/Обновление элементов каталога: системная ошибка при работе с дополнительными полями
204	Добавление/Обновление элементов каталога: дополнительное поле не найдено
244	Добавление/Обновление/Удаление элементов каталога: нет прав.
280	Добавление элементов каталога: элемент создан.
282	Элемент не найден в аккаунте.

Ответы при работе с покупателями

Подробнее о работе с покупателями читайте здесь

Другие ответы

Ошибки и ответы, не относящиеся к какому-либо конкретному разделу

остальных — 400 против 422 ответов на POST данных

спросил
9 лет, 7 месяцев назад

Изменено
6 месяцев назад

Просмотрено
524k раз

Я пытаюсь выяснить, какой правильный код состояния следует возвращать в различных сценариях с REST-подобным API, над которым я работаю. Допустим, у меня есть конечная точка, которая позволяет отправлять покупки в формате JSON. Выглядит так:

 {
    "номер_счета": 45645511,
    "уц": "004
486",
    "цена": 1.00,
    "налог": 0,08
}
 

Что я должен вернуть, если клиент отправляет мне «налог с продаж» (вместо ожидаемого «налог»). В настоящее время я возвращаю 400. Но я начал сомневаться в этом. Должен ли я действительно возвращать 422? Я имею в виду, что это JSON (который поддерживается), и это действительный JSON, просто он не содержит всех обязательных полей.

• остальное
• http-статус-коды

1

400 Bad Request теперь кажется лучшим кодом состояния HTTP/1.1 для вашего варианта использования.

Во время вашего вопроса (и моего первоначального ответа) RFC 7231 не существовал; в этот момент я возражал против 400 Bad Request , потому что RFC 2616 сказал (с моим акцентом):

Запрос не может быть понят сервером из-за неправильного синтаксиса .

, и описанный вами запрос является синтаксически допустимым JSON, заключенным в синтаксически допустимый HTTP, и, таким образом, у сервера нет проблем с синтаксисом запроса.

Однако , как указал Ли Саферит в комментариях, RFC 7231, который устаревает RFC 2616, не включает это ограничение:

Код состояния 400 (Bad Request) указывает на то, что сервер не может или не будет обрабатывать запрос из-за чего-то, что воспринимается как ошибка клиента (например, искаженный синтаксис запроса, неверный кадр сообщения запроса или ложная маршрутизация запроса).

Тем не менее, до этой переформулировки (или если вы хотите поспорить о том, что RFC 7231 является только предложенным стандартом прямо сейчас), 422 Unprocessable Entity не кажется неверным Код состояния HTTP для ваш вариант использования, потому что, как сказано во введении к RFC 4918:

Хотя коды состояния, предоставляемые HTTP/1. 1, достаточны для
описать большинство ошибок, с которыми сталкиваются методы WebDAV, там
некоторые ошибки, которые не попадают четко в существующие категории.
Эта спецификация определяет дополнительные коды состояния, разработанные для WebDAV.
методы (раздел 11)

А в описании 422 написано:

Код состояния 422 (Unprocessable Entity) означает, что сервер
понимает тип содержимого сущности запроса (следовательно,
415 (неподдерживаемый тип носителя) является недопустимым), а
синтаксис объекта запроса правильный (таким образом, 400 (неверный запрос)
код состояния является недопустимым), но не смог обработать содержащийся
инструкции.

(Обратите внимание на синтаксис; я подозреваю, что 7231 частично устарел 4918 тоже)

Это звучит как в точности как в вашей ситуации, но на всякий случай, если есть какие-то сомнения, далее следует:

Например, это состояние ошибки может возникнуть, если файл XML
тело запроса содержит правильно сформированный (т. е. синтаксически правильный), но
семантически ошибочные XML-инструкции.

(Замените «XML» на «JSON», и я думаю, что мы можем согласиться, что это ваша ситуация)

Теперь некоторые возразят, что RFC 4918 касается «HTTP-расширений для распределенного веб-авторинга и управления версиями (WebDAV)» и что вы ( предположительно) ничего не делают с WebDAV, поэтому не должны использовать его.

Имея выбор между использованием кода ошибки в исходном стандарте, который явно не охватывает ситуацию, и кодом из расширения, которое точно описывает ситуацию, я бы выбрал последний.

Кроме того, в разделе 21.4 RFC 4918 упоминается реестр кодов состояния протокола передачи гипертекста (HTTP) IANA, где можно найти 422.

Я полагаю, что для HTTP-клиента или сервера вполне разумно использовать любой код состояния из этого реестра, если они делают это правильно.

Но начиная с HTTP/1.1, RFC 7231 имеет силу, поэтому просто используйте 400 Bad Request !

21

Практический пример: GitHub API

https://docs. github.com/en/rest/overview/resources-in-the-rest-api#client-errors

мудрая идея:

Существует три возможных типа клиентских ошибок при вызовах API, которые получают тело запроса:

Отправка недопустимого JSON приведет к ответу 400 Bad Request:

 HTTP/1.1 400 Неверный запрос
Длина содержимого: 35
{"message":"Проблемы синтаксического анализа JSON"}
 

Отправка значений JSON неправильного типа приведет к ответу 400 Bad Request:

 HTTP/1.1 400 Неверный запрос
Длина содержимого: 40
{"message":"Тело должно быть объектом JSON"}
 

Отправка недопустимых полей приведет к ответу 422 Unprocessable Entity:

 HTTP/1.1 422 Необрабатываемый объект
Длина контента: 149{
  "message": "Проверка не удалась",
  "ошибки": [
    {
      "ресурс": "Выпуск",
      "поле": "название",
      "код": "отсутствует_поле"
    }
  ]
}
 

4

400 Bad Request — правильный код состояния HTTP для вашего варианта использования. Код определяется HTTP/0.9-1.1 RFC.

Запрос не может быть понят сервером из-за неправильного формата
синтаксис. Клиент НЕ ДОЛЖЕН повторять запрос без
модификации.

https://www.rfc-editor.org/rfc/rfc2616#section-10.4.1

422 Необрабатываемый объект определяется RFC 4918 — WebDav. Обратите внимание, что есть небольшая разница по сравнению с 400, см. приведенный ниже текст.

Это условие ошибки может возникнуть, если XML
тело запроса содержит правильно сформированный (т. е. синтаксически правильный), но
семантически ошибочные XML-инструкции.

Чтобы сохранить единый интерфейс, вы должны использовать 422 только в случае ответов XML, а также вы должны поддерживать все коды состояния, определенные расширением Webdav, а не только 422.

https://www.rfc-editor.org/rfc/rfc4918#page-78

См. также сообщение Марка Ноттингема о кодах состояния:

ошибочно пытаться отобразить каждую часть вашего приложения «глубоко»
в коды состояния HTTP; в большинстве случаев уровень детализации вы
хочу стремиться к гораздо грубее. В случае сомнений можно использовать
общие коды состояния 200 OK, 400 Bad Request и 500 Internal
Ошибка службы, когда нет лучшего соответствия .

Как думать о кодах состояния HTTP

4

Чтобы отразить состояние на 2015 год:

Поведенческие коды ответов 400 и 422 будут рассматриваться клиентами и посредниками одинаково, поэтому на самом деле это не делает конкретной разницы , которую вы используете.

Однако я ожидаю, что 400 в настоящее время используется более широко, и, кроме того, пояснения, которые дает спецификация HTTPbis, делают его более подходящим из двух кодов состояния:

• Спецификация HTTPbis поясняет, что значение 400 предназначено не только для синтаксических ошибок. Теперь используется более широкая фраза «указывает, что сервер не может или не будет обрабатывать запрос из-за чего-то, что воспринимается как ошибка клиента».
• 422 является расширением WebDAV и не упоминается в RFC 2616 или в более новой спецификации HTTPbis.

Для контекста: HTTPbis — это пересмотр спецификации HTTP/1.1, который пытается прояснить неясные или противоречивые области. Как только он достигнет одобренного статуса, он заменит RFC2616.

3

Правильного ответа нет, так как он зависит от определения «синтаксиса» для вашего запроса. Самое главное, чтобы вы:

1. Постоянно использовали код(ы) ответа
2. Включите в тело ответа как можно больше дополнительной информации, чтобы помочь разработчикам, использующим ваш API, понять, что происходит. =

Перед тем, как все накинутся на меня за то, что здесь нет правильного или неправильного ответа, позвольте мне немного объяснить, как я пришел к такому выводу.

В этом конкретном примере вопрос OP касается запроса JSON, который содержит ключ, отличный от ожидаемого. Теперь полученное имя ключа очень похоже с точки зрения естественного языка на ожидаемый ключ, но строго отличается от него и, следовательно, (обычно) не распознается машиной как эквивалентное.

Как я сказал выше, решающим фактором является то, что подразумевается под синтаксисом . Если запрос был отправлен с типом контента application/json , то да, запрос равен синтаксически действителен, потому что это допустимый синтаксис JSON, но не семантически действителен, поскольку он не соответствует ожидаемому. (при условии строгого определения того, что делает рассматриваемый запрос семантически действительным или нет).

Если, с другой стороны, запрос был отправлен с более конкретным пользовательским типом контента, например application/vnd.mycorp.mydatatype+json , который, возможно, указывает, какие именно поля ожидаются, то я бы сказал, что запрос может легко быть синтаксически недопустимым, отсюда и ответ 400.

В рассматриваемом случае, поскольку ключ был неверным, а не значение , возникла ошибка синтаксиса , если существовала спецификация для допустимых ключей. Если бы не было спецификации для действительных ключей или ошибка была со значением , тогда это была бы семантическая ошибка .

3

422 Объяснение необрабатываемого объекта Обновлено: 6 марта 2017 г.

Что такое необрабатываемый объект 422?

Код состояния 422 появляется, когда запрос правильно сформирован, однако из-за
к семантическим ошибкам он неспособен обрабатываться. Этот статус HTTP был
представлен в RFC 4918 и более конкретно ориентирован на HTTP
расширения для распределенной веб-авторизации и управления версиями (WebDAV).

Существуют некоторые разногласия по поводу того, должны ли разработчики
должен возвращать клиентам ошибку 400 vs 422 (подробнее о различиях
между обоими статусами ниже). Однако в большинстве случаев соглашаются
при этом статус 422 должен возвращаться только в том случае, если вы поддерживаете WebDAV
возможности.

Дословное определение кода состояния 422, взятое из раздела
11.2 в RFC 4918 можно прочитать ниже.

Код состояния 422 (Unprocessable Entity) означает, что сервер
понимает тип содержимого сущности запроса (следовательно,
415 (неподдерживаемый тип носителя) является недопустимым), а
синтаксис объекта запроса правильный (таким образом, 400 (неверный запрос)
код состояния является недопустимым), но не смог обработать содержащийся
инструкции.

Далее в определении говорится:

Например, это состояние ошибки может возникнуть, если тело запроса XML
содержит правильно сформированные (т. е. синтаксически правильные), но семантически
ошибочные XML-инструкции.

400 vs 422 Коды состояния

Ошибки неверного запроса используют код состояния 400 и должны быть
возвращается клиенту, если синтаксис запроса искажен, содержит
неверный кадр сообщения запроса или маршрутизация запроса с вводом в заблуждение.
Этот код состояния может показаться очень похожим на 422 unprocessable.
статус объекта, однако, одна небольшая часть информации, которая
их отличает тот факт, что синтаксис объекта запроса для
ошибка 422 верна, тогда как синтаксис запроса, который генерирует
ошибка 400 неверна.

Использование статуса 422 должно быть зарезервировано только для особых случаев.
сценарии использования. В большинстве других случаев, когда ошибка клиента произошла из-за
неправильно сформированный синтаксис, следует использовать статус 400 Bad Request.

https://www.keycdn.com/support/422-unprocessable-entity/

Ваш случай: HTTP 400 является правильным кодом состояния для вашего случая с точки зрения REST, так как синтаксически неверно отправлять sales_tax вместо tax , хотя это допустимый JSON. Обычно это применяется большинством фреймворков на стороне сервера при сопоставлении JSON с объектами. Однако есть некоторые реализации REST, которые игнорируют новый ключ в объекте JSON. В этом случае пользовательская спецификация типа содержимого для приема только допустимых полей может быть принудительно применена на стороне сервера.

Идеальный сценарий для 422:

В идеальном мире 422 предпочтительнее и обычно приемлемо для отправки в качестве ответа, если сервер понимает тип содержимого объекта запроса и синтаксис объекта запроса верен, но был не может обработать данные, потому что они семантически ошибочны.

Ситуации 400 над 422:

Помните, что код ответа 422 является расширенным кодом состояния HTTP (WebDAV). Все еще есть некоторые HTTP-клиенты/интерфейсные библиотеки, которые не готовы обрабатывать 422. Для них это так же просто, как «HTTP 422 неверен, потому что это не HTTP» . С точки зрения обслуживания, 400 не совсем конкретно.

В архитектуре предприятия службы развертываются в основном на уровнях служб, таких как SOA, IDM и т. д. Обычно они обслуживают несколько клиентов, начиная от очень старого собственного клиента и заканчивая новейшими HTTP-клиентами. Если один из клиентов не обрабатывает HTTP 422, можно попросить клиента обновить или изменить код ответа на HTTP 400 для всех. По моему опыту, это очень редко в наши дни, но все же возможно. Таким образом, перед принятием решения о кодах ответа HTTP всегда требуется тщательное изучение вашей архитектуры.

Чтобы справиться с такой ситуацией, сервисные уровни обычно используют версии или настраивают флаг конфигурации для строгой совместимости клиентов с HTTP для отправки 400 и отправки 422 для остальных из них. Таким образом, они обеспечивают поддержку обратной совместимости для существующих потребителей, но в то же время дают возможность новым клиентам использовать HTTP 422.

В последнем обновлении RFC7321 говорится:

 сервер не может или
   не будет обрабатывать запрос из-за чего-то, что воспринимается как
   ошибка клиента (например, неверный синтаксис запроса, неверный запрос
   кадрирование сообщений или обманная маршрутизация запросов). 
 

Это подтверждает, что серверы могут отправлять HTTP 400 для недопустимого запроса. 400 больше не относится только к синтаксической ошибке , однако 422 по-прежнему является подлинным ответом, если клиенты могут его обработать.

Во-первых, это очень хороший вопрос.

400 Неверный запрос — когда в запросе отсутствует важная часть информации

, например. Заголовок авторизации или заголовок типа контента. Что абсолютно необходимо серверу для понимания запроса. Это может отличаться от сервера к серверу.

422 Unprocessable Entity — Когда тело запроса не может быть проанализировано.

Это менее опасно, чем 400. Запрос достиг сервера. Сервер подтвердил, что запрос имеет правильную базовую структуру. Но информация в теле запроса не может быть проанализирована или понята.

напр. Content-Type: application/xml , если тело запроса — JSON.

Вот статья со списком кодов состояния и их использованием в REST API.
https://metamug.com/article/status-codes-for-rest-api.php

4

кодов состояния http — 400 против 422 для запроса об ошибке клиента

Я прочитал много сообщений и статей о правильном коде состояния http для возврата в случае ошибки запроса клиента.
Другие предлагают использовать 400, так как он был переопределен в RFC 7231, хотя я не уверен, что приведенный пример охватывает все ошибки клиента, на мой взгляд, потому что примеры синтаксические.

Код состояния 400 (неверный запрос) указывает, что сервер не может или
не будет обрабатывать запрос из-за чего-то, что воспринимается как
ошибка клиента (например, неверный синтаксис запроса, неверный запрос
кадрирование сообщений или ложная маршрутизация запросов).

Я нашел это утверждение в Приложении B RFC 7231:

Код состояния 400 (неверный запрос) был ослаблен, поэтому
не ограничивается синтаксическими ошибками. (раздел 6.5.1)

Означает ли это, что я могу считать любую ошибку клиента неверным запросом? Не лучше ли использовать 400 для клиентских запросов и просто указывать более конкретную ошибку в сообщении?

С другой стороны, другие говорят, что лучше использовать 422 (Unprocessable Entity). Хотя это больше ориентировано на семантику, оно указано только в [RFC 4918][2], который является расширением webDAV для http/1.1.

Код состояния 422 (Unprocessable Entity) означает, что сервер
понимает тип содержимого объекта запроса (поэтому код состояния
415 (Unsupported Media Type) не подходит), а синтаксис
объекта запроса является правильным (таким образом, 400 (Bad Request)
код состояния является недопустимым), но не смог обработать содержащийся
инструкции. Например, это состояние ошибки может возникнуть, если тело запроса XML
содержит правильно сформированный (т. е. синтаксически правильный), но
семантически ошибочный, инструкции XML.

Могу ли я использовать эти коды расширения webDAV для обработки своих HTTP-запросов? В случае с 422, могу ли я использовать его, даже если его нет в основных http-кодах.

Должен ли я использовать 400 или 422 для моей ошибки клиента?

Вот возможные ошибки клиента, которые я имею в виду:

 1.) Неверный параметр. Клиент предоставил параметры, но они признаны недействительными. Пример: я сказал, что userId равен 1, но когда я проверил, нет userId, равного 1. Еще одним примером недопустимого параметра является неправильный тип данных.
 2.) Отсутствуют обязательные параметры
 3.) Допустим, мне нужно хэшировать значение на основе заданных параметров, и это не удалось
 4.) Используется заблокированный контент. Например, я хочу подать заявку на членство, и я передал идентификатор пользователя 1. Однако идентификатор пользователя одного заблокирован/деактивирован
 5.) Когда я пытаюсь удалить запись, но она все еще используется в другой таблице.
 6.