Errors and request results
How to interpret HTTP status, success, and status and handle results
There are two levels to a response: the HTTP status describes how the request was handled, while the JSON fields describe the operation or tracking result.
Reading a response
- Check the HTTP status. Handle responses outside the
2xxrange as errors. If the response body is JSON, read its error details. - For a
2xxresponse, checksuccessandstatuswhere the operation defines them. For example, the companies endpoint returnssuccessanddatawithoutstatus. success: truewithstatus: "OK"means tracking data was retrieved. Usedata.success: truewithstatus: "INFO_NOT_FOUND"means the search completed but found no data for that number and carrier. This is not a processing failure. The current API returns this result with HTTP200anddata: null.success: falsemeans the result could not be retrieved. Checkstatusfor the reason: for example,LINE_NO_RESPONSEmeans the carrier’s data source did not respond in time, whileUNEXPECTED_ERRORindicates an unexpected processing failure.
HTTP 200 alone does not guarantee that tracking data is available. A stored tracking result may contain success: false, and a batch status response may include individual errors in data.results. Check each result separately.
Use status for programmatic handling. status_description contains a text description of the result or error. Its wording may change, so use the status code for programmatic handling.
Quick troubleshooting
401,403, orAPI_KEY_WRONG. Check thatapi_keyis present, the key has not been revoked, and its full value was copied.INFO_NOT_FOUND. Checkvalue,type, and the carrier’s SCAC code. Confirm support for that type in the companies list.company=AUTOis available only for containers.429orAPI_KEY_RATE_LIMIT. The request rate exceeded the limit. UseRetry-After, if present, to determine when to try again. Tracking requests are limited to 8 per minute. Retrieving a batch task’s status has a separate limit listed under Limits.LINE_NO_RESPONSE. The carrier did not respond in time. Try again later.
HTTP statuses
| HTTP status | Meaning and action |
|---|---|
2xx | The request was handled. Check the JSON result fields. Tracking data may still be unavailable. |
400 | Check required parameters, value formats, and the request body. Read the response for details. |
401 / 403 | Check your API key and permissions. |
404 | The path or resource was not found. Check the URL and resource ID. |
429 | Reduce the request rate and respect Retry-After if present. |
5xx | The server or data source could not process the request. Retry with increasing delays. If the error persists, contact support@timetocargo.com. |
Result codes
status | Meaning |
|---|---|
OK | The request succeeded. The result is in data. |
WRONG_PARAMS | Required parameters are missing, or query parameters or body fields contain invalid values. |
INFO_NOT_FOUND | No tracking data was found for this number and carrier. |
LINE_IS_UNDER_MAINTENANCE | Tracking for this carrier is temporarily suspended while its data source is being maintained or updated. |
LINE_NO_RESPONSE | The carrier’s data source did not respond in time. |
API_KEY_WRONG | The API key is invalid, has been revoked, or is malformed. |
UNAUTHORIZED | The api_key parameter was not provided. |
API_KEY_LIMIT_REACHED | The API key’s tracking quota has been exhausted. |
API_KEY_RATE_LIMIT | The request rate limit for the API key was exceeded. |
LOW_BALANCE | There are not enough tracking credits on the account. |
SERVICE_UNAVAILABLE | The service is temporarily unavailable. Try again later. |
NOT_FOUND | The requested resource was not found. |
UNEXPECTED_ERROR | An unexpected error occurred while processing the request. Retry. If the error persists, contact support@timetocargo.com. |
Errors involving a route or an ID format may use error and code instead of status_description and status. Account for this when displaying an error message.
For persistent 5xx or UNEXPECTED_ERROR responses, contact support@timetocargo.com. For billing and account questions, contact info@timetocargo.com.
Last updated on