Ошибки и результаты запросов
Как читать HTTP-статус, success и status и обрабатывать результаты
Результат запроса описывается на двух уровнях: HTTP-статус показывает, как обработан запрос, а поля JSON уточняют результат операции или отслеживания.
Как читать ответ
- Проверьте HTTP-статус. Ответ вне диапазона
2xxтребует обработки ошибки. Если тело содержит JSON, прочитайте пояснение из него. - В ответе
2xxпроверьтеsuccessиstatus, если эти поля предусмотрены операцией. Например, список компаний возвращаетsuccessиdataбезstatus. success: trueвместе соstatus: "OK"означает, что результат отслеживания получен. Используйтеdata.success: trueвместе соstatus: "INFO_NOT_FOUND"означает, что поиск выполнен, но данных для указанного номера и перевозчика нет. Это не сбой обработки. В текущем API такой результат возвращается с HTTP200иdata: null.success: falseозначает, что результат получить не удалось. Полеstatusпомогает определить причину: например,LINE_NO_RESPONSE— источник данных перевозчика не ответил вовремя, аUNEXPECTED_ERROR— непредвиденная ошибка обработки.
Не считайте любой HTTP 200 подтверждением наличия данных. В частности, сохранённый результат отслеживания может содержать success: false, а ответ на запрос состояния batch-задачи — отдельные ошибки внутри data.results. Проверяйте каждый результат отдельно.
status содержит код для программной обработки. status_description содержит текстовое описание результата или ошибки. Формулировка может меняться, поэтому для обработки используйте код status.
Быстрая диагностика
401,403илиAPI_KEY_WRONG. Проверьте, что параметрapi_keyпередан, ключ не отозван и скопирован полностью.INFO_NOT_FOUND. Проверьте номерvalue, егоtypeи SCAC-код перевозчика. Убедитесь, что перевозчик поддерживает выбранный тип в списке компаний.company=AUTOдоступно только для контейнеров.429илиAPI_KEY_RATE_LIMIT. Превышена допустимая частота запросов. Чтобы определить время до следующей попытки, используйте заголовокRetry-After, если он передан. Ограничение запросов на отслеживание — до 8 в минуту. Для получения состояния пакетной задачи действует отдельный лимит, указанный в ограничениях.LINE_NO_RESPONSE. Перевозчик не ответил в отведённое время. Повторите запрос позже.
HTTP-статусы
| HTTP-статус | Что означает и что делать |
|---|---|
2xx | Запрос обработан. Проверьте поля результата в JSON. Данные отслеживания могут отсутствовать. |
400 | Проверьте обязательные параметры, формат значений и тело запроса. Причина указана в ответе. |
401 / 403 | Проверьте API-ключ и права доступа. |
404 | Запрошенный путь или ресурс не найден. Проверьте URL и идентификатор ресурса. |
429 | Снизьте частоту запросов и учитывайте Retry-After, если он передан. |
5xx | Сервер или источник данных не смог обработать запрос. Повторите попытку, увеличивая интервал между запросами. Если ошибка сохраняется, обратитесь в поддержку по адресу support@cargotime.ru. |
Коды результата
status | Значение |
|---|---|
OK | Запрос выполнен успешно. Результат находится в data. |
WRONG_PARAMS | Не переданы обязательные параметры или указаны недопустимые значения параметров либо полей тела. |
INFO_NOT_FOUND | По указанному номеру и перевозчику данные не найдены. |
LINE_IS_UNDER_MAINTENANCE | Получение данных от перевозчика временно приостановлено: источник находится на обслуживании или доработке. |
LINE_NO_RESPONSE | Источник данных перевозчика не ответил в отведённое время. |
API_KEY_WRONG | API-ключ недействителен, отозван или имеет неверный формат. |
UNAUTHORIZED | Параметр api_key не был передан. |
API_KEY_LIMIT_REACHED | Лимит доступных отслеживаний для API-ключа исчерпан. |
API_KEY_RATE_LIMIT | Превышена допустимая частота запросов для API-ключа. |
LOW_BALANCE | На балансе недостаточно доступных отслеживаний. |
SERVICE_UNAVAILABLE | Сервис временно недоступен. Повторите запрос позже. |
NOT_FOUND | Запрошенный ресурс не найден. |
UNEXPECTED_ERROR | При обработке произошла непредвиденная ошибка. Повторите запрос. Если ошибка сохраняется, обратитесь в поддержку по адресу support@cargotime.ru. |
Для ошибок маршрута или формата идентификатора тело может содержать error и code вместо status_description и status. Учитывайте этот вариант при выводе сообщения об ошибке.
Если ошибки 5xx или UNEXPECTED_ERROR сохраняются, обратитесь в поддержку по адресу support@cargotime.ru. По вопросам оплаты и аккаунта — info@cargotime.ru.
Обновлено