HTTP Codes

Altruist Public API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP (Hypertext Transfer Protocol) codes are three-digit status codes returned by servers in response to a client's request. These three categories of codes are used in the Altruist Public API:

• 2xx codes indicate the success of the API call.
• 4xx codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
• 5xx codes indicate an error with Altruist's servers.

Status 2xx Codes

200 is a successful response for the API request.

204 is no content is rerurned for the API request.

Status 4xx Codes

4xx codes indicate a problem with the request which the client can resolve.

The most frequent 4xx errors are:

• Authentication errors (401, 403)
• Rate limiting errors (429)
• Request body validation errors (400, 404)

Sample 4xx Responses

400

{
  "error": "bad_request",
  "message": "invalid or missing user id"
}

401

{
  "error": "unauthorized",
  "message": "user is not authorized"
}

403

{
  "error": "forbidden",
  "message": "User is forbidden to access this resource"
}

404

{
  "error_type": "resource_not_found",
  "message": "Data feed not found"
}

429

{
  "error": "many_requests",
  "message": "Too many requests. Please wait and try again later."
}

Status 5xx Codes

5xx codes typically indicate problems on the server side.
These range from configuration problems to internal network connectivity problems.

They may be transient, only affecting a single call, or long-lasting, impacting every single call over a long period of time.

A client will not be able to resolve these issues.

The most common example of 5xx errors are timeouts.

Sample 5xx Response

500

{
  "error": "internal_error",
  "message": "unable to connect to the data source"
}

503

{
  "error": "service_unavailable",
  "message": "unable to connect to the service"
}