Здравствуйте, Буравчик, Вы писали:

Б>Какие HTTP status code используются в ваших API?
если ошибка клиента (неправильный запрос) — 4**. неправильный запрос — это значит что клиенту не следует повторять запрос в том же виде, без изменений.
если сервера — 500 (это перегрузка сервера, неожидаемые ошибки при обработке реквеста). ошибка сервера — это когда запрос составлен верно, но сервер по каким-то причинам не смог.

Б>Передаете ли дополнительную информацию об ошибках? Какую?
если для целей обработки ошибки на клиенте нужна эта доп. информация — передаём.
можно в заголовке, типа X-Reason: какой-то доп. код/идентификатор поясняющий что не так.

Б>Код ошибки, текстовое сообщение, на каком языке (русский, английский), дополнительные параметры?
это зависит. если система (и апи) в основном для русскоязычных — можно на русском.
всё дополнительное определяется конкретикой, если вызвающей стороне нужна/плезна доп. информация о том, что не так — можно включить.

Б>Что возвращаете, если клиент запрашивает существующий ресурс, к которому запрещен доступ:
Б>404 или 403?
403 ближе к сути, но есть нюанс, если надо скрыть что такой ресурс существует (защита от перебора), то можно и 404.

есть практика http использовать в качестве транспорта (аля JSON-RPC), в этом случае ответ всегда 200 и инфа об ошибке в теле ответа.
но наша практика показала, что использование http кодов ответа тоже норм, особенно с учетом, что их в любом случае придется обрабатывать (может оказаться реально плохой запрос, прокси, и прочее)
то лучше тогда уж сразу на них ориентироваться. бытует мнение что кодов недостаточно (это так), но если в хидере или теле возвращать доп. информацию (если надо), то всё ок.

Здравствуйте, Буравчик, Вы писали:

Б>Какие HTTP status code используются в ваших API?
если ошибка клиента (неправильный запрос) — 4**. неправильный запрос — это значит что клиенту не следует повторять запрос в том же виде, без изменений.
если сервера — 500 (это перегрузка сервера, неожидаемые ошибки при обработке реквеста). ошибка сервера — это когда запрос составлен верно, но сервер по каким-то причинам не смог.

Б>Передаете ли дополнительную информацию об ошибках? Какую?
если для целей обработки ошибки на клиенте нужна эта доп. информация — передаём.
можно в заголовке, типа X-Reason: какой-то доп. код/идентификатор поясняющий что не так.

Б>Код ошибки, текстовое сообщение, на каком языке (русский, английский), дополнительные параметры?
это зависит. если система (и апи) в основном для русскоязычных — можно на русском.
всё дополнительное определяется конкретикой, если вызвающей стороне нужна/плезна доп. информация о том, что не так — можно включить.

Б>Что возвращаете, если клиент запрашивает существующий ресурс, к которому запрещен доступ:
Б>404 или 403?
403 ближе к сути, но есть нюанс, если надо скрыть что такой ресурс существует (защита от перебора), то можно и 404.

есть практика http использовать в качестве транспорта (аля JSON-RPC), в этом случае ответ всегда 200 и инфа об ошибке в теле ответа.
но наша практика показала, что использование http кодов ответа тоже норм, особенно с учетом, что их в любом случае придется обрабатывать (может оказаться реально плохой запрос, прокси, и прочее)
то лучше тогда уж сразу на них ориентироваться. бытует мнение что кодов недостаточно (это так), но если в хидере или теле возвращать доп. информацию (если надо), то всё ок.

также использование хттп статус кодов, упрощает анализ логов веб-сервера. сразу можно фильтровать ошибки, иначе придется что-то дополнительно мутить.