Amperity API response codes

Amperity API endpoints use conventional HTTP response status codes—3-digit numbers where the first digit of the code defines the class of response—to indicate success or failure for any API request. Response status codes fall into three categories:

  1. 2xx - Success

  2. 4xx - Error

    A 4xx error occurs when information in a request is invalid, such as requesting access to an endpoint that does not exist or by including the wrong value for a query parameter.

  3. 5xx - Error

    A 5xx error is caused when the API or endpoint is unavailable.

2xx status codes

The 2xx class of status codes indicate that your request was successfully received, understood, and accepted by your Amperity tenant.

Status code

Description

200 OK

A request completed successfully.

4xx status codes

The 4xx class of status codes indicate that your request experienced a fatal client error.

When a request returns a fatal client error, the standard error response will include the following:

  • status The status code for the error.

  • message A human readable error message.

  • request_id Optional. An Amperity request ID.

  • trace_id Optional. An Amperity tracing ID.

For example:

{
  "status": 400,
  "message": "Error updating database: Can't find campaign named \
              'CampaignName'",
  "request_id":"1ab23456-c78d-9012-3456-78efg9hi01j2",
  "trace_id":"1a2b3456789cd0ef1g234hijklm5nopq"
}

Status code

Description

400 Bad Request

A request did not contain a required parameter or has an invalid parameter.

401 Authentication Required

A request contains invalid authentication or was using an invalid version identifier.

403 Not Authorized

A request contains valid authentication, but does have permission to perform the requested action.

404 Not Found

A request was made to a resource that does not exist.

405 Method not Allowed

A request used an unsupported HTTP method.

409 Conflict

A request conflicts with the current state.

429 Too Many Requests

A rate limit has been exceeded.

Note

Amperity does not currenctly enforce a rate limit.

Tip

Watch for 429 error codes and build a retry mechanism into the integrations or applications that interact with the Amperity API. Use an exponential backoff schedule with some randomness built in to reduce request volume.

5xx status codes

The 5xx class of status codes indicate a fatal server error. When your integration or application experiences a 5xx error, use an exponential backoff schedule with some randomness built in to reduce request volume.

Status code

Description

500 Server Error

An internal error occurred. Simplify the request or retry with exponential backoff.

503 Service Unavailable

The server is currently unavailable.

Tip

Watch for 503 error codes and build a retry mechanism into the integrations or applications that interact with the Amperity API.