Errors

Afi uses conventional HTTP response status codes to indicate the success or failure of an API request. In general:

  • Status codes in the 2xx range indicate success.
  • Status codes in the 4xx range indicate an error that failed given the information provided and current state (e.g., a required parameter was omitted, invalid value was sent, etc).
  • Status codes in the 5xx range indicate an error with the Afi services (these errors are rare).

HTTP status codes summary:

HTTP Status codeDescription
200 - OKCall succeeded.
400 - Bad RequestThe request failed, often due to missing a required parameter, invalid parameter or their combination.
401 - UnauthorizedNo valid API key provided.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request. Often happens when already executed request is retried one more time (e.g. if the previous request was retried to early and its response was lost).
429 - Too Many Requests Too many requests hit the API too quickly. Caller should use exponential backoff of its requests.
5xx - Server Errors Something went wrong on Afi side (these errors are rare). Request can be retried with an exponential backoff.

Note, Status codes 429 and 5xx can be retried with an exponential backoff.

For enable troubleshooting and automatic error handling in the application logic, errors include a JSON body with the following details:

Error JSON fieldDescription
status (integer)HTTP status code.
code (string)An error code string that uniquely identifies the error type reported.
message (string)Human readable error message.