Successful requests will return a 200 - OK HTTP status code. If the request fails, the response will contain a key error on the top level, and a 4XX or 5XX HTTP status code. Errors are returned as JSON objects in the following format:

{
  "error": {
    "code": 400,
    "type": "bad_request",
    "details": [
      "first_name: Field is required"
    ]
  }
}

The error type will be one of bad_request, not_found, unauthorized, forbidden, rate_limit_exceeded, server_error.

A full list of returned status codes can be found below:

Status CodeDescription
200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe API key doesn’t have permissions to perform the request.
404 - Not FoundThe requested resource doesn’t exist.
429 - Too Many RequestsToo many requests hit the API too quickly. We currently don’t rate limit requests, but we may do in future.
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. This is rare.
AuthenticationQuickstart