Our API responses use standard HTTP status codes: 2xx status codes indicate success, 4xx status codes indicate invalid input or invalid action on current state, and 5xx status codes indicate a rare error on Persona's servers.

Error handling

Errors that you will receive from Persona fall into three major categories:

• Client errors: Invalid content in the API request.
• Network errors: Intermittent communication problems between client and server.
• Server errors: A problem on Persona's servers.

A list of all error codes is provided at the end of this page.

Client errors

Client errors result from invalid content of an API request. They return an HTTP response with a 4xx error code. For example, the server may return a 401 if you provide an invalid API key, or a 422 if invalid parameters were provided. For client errors, we generally recommend correcting the original request and trying again.

For a POST operation using an idempotency key, Persona will cache the results of requests as long as the API call was acknowledged. This means that a request that returns a 400 sends back the same 400 if followed by a new request with the same idempotency key. We recommend generating a fresh idempotency key when modifying the original request to get a successful result.

There are caveats to the above. For example, if you receive a 429 error due to your request being rate limited, subsequent requests with the same idempotency key will still run because rate limiters are executed before the API's idempotency layer. Similarly, the same goes for a 401 due to an invalid API key. Even so, the safest strategy to address most 4xx errors is to generate a new idempotency key, correcting the request, and trying again.

Network errors

Network errors are the result of connectivity problems between client and server. These will likely result in low-level errors from your HTTP client library, like socket or timeout exceptions. For example, a client may time out while trying to read from Persona's servers, or an API response might never be received because a connection terminates prematurely. Although a network error seems like it will succeed after you fix the connectivity problems, sometimes there's another type of error hiding in the intermittent problem.

📘

POST requests with large request bodies often are the root cause of timeout errors. We strongly recommend evaluating your HTTP client's timeout settings when sending such requests. In addition, modifying the content-type to use multipart/form-data often also helps reduce such errors.

Network errors are where the value of idempotency keys and request retries are most obvious. When intermittent problems occur, the client library is usually left in a state where it does not know whether or not the server received the request.

For network errors, the client should retry such requests with the same idempotency key and the same parameters until it's able to receive a result from the server. Sending the same idempotency key with different parameters produces an error indicating that the new request didn't match the original.

Server errors

Server errors result from a problem with Persona's servers. They return an HTTP response with a 5xx error code. These errors are the most difficult to handle and the Persona team tries our best to ensure they occur as rarely as possible. The most likely time to observe a server error is during a production incident. You should treat the result of a server error as indeterminate.

If the request was able to reach the idempotency layer, the server will cache the result of requests. This means that retried attempts with the same idempotency key will produce the same result. However, unlike for client errors, this is not guaranteed due to the server potentially being fully unavailable and the request not being successfully processed by the idempotency layer.

For server errors, we recommend retrying with new requests and new idempotency keys if it is safe for your use case. In addition, we recommend leveraging reference_id and Accounts to properly group requests to make it easy to track objects that were re-created.

Error codes

When an error is encountered, the response body contains a list of errors with title and details.

{
  "errors": [
    {
      "title": "Bad Request",
      "details": "data.attributes.name is missing"
    }
  ]
}

Below is a list of possible error codes with their meanings.