Response Codes
Each API request answers with an HTTP status code that tells you how it went.
Status code overview
Successful responses (2XX)
- 200 OK: The request was processed, and the data is in the response.
Client errors (4XX)
- 400 Bad Request: Something in the request is wrong. This includes a malformed or invalid parameter, a date range that is too long, an invalid cursor, and a missing or invalid
Connection-Idheader (it must be the id of one of your connections). - 401 Unauthorized: Your API key is missing, invalid or expired. Send a valid
x-api-keyheader. - 403 Forbidden: Your account does not have the feature the endpoint needs (for example Analytics or Validation Engine).
- 404 Not Found: The resource does not exist on the connection, for example an unknown safety event or accident id.
- 429 Too Many Requests: You have reached the rate limit. Retry after a delay, with exponential backoff. The Safety Scores export routes (
/reports/safety-scores/exportand/reports/safety-scores/drivers/export) have a daily limit of 1,000 calls per API key: once it is used up, retrying does not help until the time in theX-RateLimit-Resetheader (midnight UTC).
Server errors (5XX)
- 500 Internal Server Error: The server met an unexpected problem. Retry after a short delay.
- 503 Service Unavailable: The service, or the data behind an endpoint, is temporarily unavailable. Retry after a delay.
Error response
Most errors come back in the same envelope as a successful response, with data empty (a few validation errors answer with the message alone):
{
"status": 400,
"message": "Connection not found",
"data": null,
"next": null
}Use the message for debugging, but do not code against its exact text: it can change without a new API version.
Error handling tips
- Check parameters: for a 400, check that all required parameters and headers are present and well formed, including
Connection-Id. - Authenticate properly: include a valid
x-api-keyin every request to avoid 401. - Mind the limits: for a 429, slow down and back off exponentially.
- Retry a 429, 500 or 503 after a delay that grows with each attempt.
- Log errors with the request and the
message, for diagnosis.
Updated 1 day ago
Did this page help you?