Errors - Auxia Docs

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

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error caused by the request, such as a missing required field, an invalid API key, or a reference to a resource that does not exist. Except for 429, retrying the same request will not succeed.
Codes in the 5xx range indicate an error on Auxia’s side. These are rare, and are usually safe to retry.

Error response

Every error response from the API has an application/json body with the following attributes.

Attribute	Type	Description
`code`	Integer	The HTTP status code of the response. Always the same as the status line.
`message`	String	A human-readable description of the error. Messages are for developers and may change; do not parse them or branch on them.

{
  "code": 400,
  "message": "user_id must be set in request"
}

Some messages end with a reference ID, such as Reference A0D3427F89CACF13.F26AB72FAA88C751 or [ID: 66A1855B08B0DF57.057CA4DCB18714FF; ...]. Include it when you contact Auxia about a failed request.

HTTP status code summary

Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request was invalid, often because a required field is missing, a value is malformed, or the body is not valid JSON.
403	Forbidden	The API key is missing, invalid, or does not have permission to call this API for this project. Auxia returns `403` for all API key failures; it does not return `401`.
404	Not Found	The project, or another resource the request refers to, does not exist. Also returned for an unknown API path.
405	Method Not Allowed	The API was called with an HTTP method other than `POST`.
409	Conflict	The request conflicts with a resource that already exists, for example a treatment with the same `external_treatment_id`.
413	Payload Too Large	The request body is larger than 1 MiB, or 16 MiB for Insert Treatment and Update Treatment.
429	Too Many Requests	The project exceeded the request rate limit for this API. See Rate limits.
500	Internal Server Error	An unexpected error or an internal timeout occurred on Auxia’s side.
502	Bad Gateway	Auxia’s load balancer could not get a response from the API.
503	Service Unavailable	Auxia is temporarily unable to handle the request.
504	Gateway Timeout	The API gateway did not get a response within its time limit.

Server errors

A 500 response has the standard error body:

{
  "code": 500,
  "message": "An unexpected error occurred; please contact Auxia for more information. [ID: 66A1855B08B0DF57.057CA4DCB18714FF; MI: 16DBD8420A570FAA; P: auxia-gcp]"
}

A timeout inside Auxia also returns 500, with error code E4896 in the message. 503 and 504 responses returned by the API use the same format. A 5xx response returned by Auxia’s load balancer, rather than by the API itself, has a text/html body instead. For example, a 502:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>502 Server Error</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Server Error</h1>
<h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2>
<h2></h2>
</body></html>

Handle server errors by status code, not by body.

Handling errors

Code	Retry?	What to do
400, 404, 405, 413	No	Fix the request. The `message` identifies the problem.
403	No	Check that the API key is correct, is sent in the `x-api-key` header, and has the key type this API requires.
409	No	The resource already exists. Read it, or update it instead of inserting it.
429	Yes	Wait for the number of seconds in the `Retry-After` header, then retry.
500	Yes, if the API is safe to retry	Retry with exponential backoff, a small number of times. If the error persists, contact Auxia with the reference ID.
502, 503, 504	Yes, if the API is safe to retry	Retry with exponential backoff and jitter.

When you retry, use exponential backoff with jitter: wait about 1 second before the first retry, double the wait after each attempt, and add a random delay. Cap the number of attempts so that a sustained outage does not multiply your traffic.

Retry safety

A request that fails with a 5xx error, or times out on your side, may still have been applied. Before you retry a request that writes data, check whether a duplicate would cause a problem.

API	Safe to retry	Notes
Get Treatments	Yes	Each call is a new decision with a new `responseId`. Use the treatments from the response you render.
Get Treatment, Get All Treatments, Get DataFields	Yes	Read-only.
Insert Surface, Insert Data Field	Yes	Idempotent. Inserting an item that already exists returns the existing item.
Insert Treatment Type	Yes	An identical request returns the existing treatment type. A different request with the same name returns `409`.
Update Treatment Type, Update Treatment	Yes	Repeating the same update produces the same result.
Insert Treatment	With `external_treatment_id`	Set `external_treatment_id` so that a retry of an insert that already succeeded returns `409` instead of creating a second treatment.
Log Treatment Interaction	With care	Interactions are not deduplicated. A retry of a request that already succeeded may record the interaction twice.
Log Events	With `insertId`	Set `insertId` on each event so that retried events can be deduplicated.

Rate limits

Insert Treatment and Update Treatment can be rate-limited per project. When a project exceeds its limit, the API returns 429 with these headers:

Header	Description
`Retry-After`	Seconds to wait before retrying.
`X-RateLimit-Limit`	The maximum number of requests per second allowed for the project.
`X-RateLimit-Remaining`	The number of requests remaining in the current window.

Testing error handling

To test how your integration handles errors, stub the Auxia API in your own test environment and return the status codes and bodies on this page. Auxia does not provide a way to trigger server errors on demand.

​Error response

​HTTP status code summary

​Server errors

​Handling errors

​Retry safety

​Rate limits

​Testing error handling