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-Id header (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-key header.
  • 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/export and /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 the X-RateLimit-Reset header (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

  1. Check parameters: for a 400, check that all required parameters and headers are present and well formed, including Connection-Id.
  2. Authenticate properly: include a valid x-api-key in every request to avoid 401.
  3. Mind the limits: for a 429, slow down and back off exponentially.
  4. Retry a 429, 500 or 503 after a delay that grows with each attempt.
  5. Log errors with the request and the message, for diagnosis.

Did this page help you?