Errors

AgencyMax APIs use standard HTTP status codes. Error responses from the APIs use the Problem Details format (RFC 9457) with the content type application/problem+json.

Status codes

Status	Meaning
200 OK	The request succeeded.
201 Created	A resource was created. The Location header holds its URL.
204 No Content	The request succeeded and there's no response body, as with deletes and validation-only calls.
400 Bad Request	The request is invalid: a field failed validation, or a value such as a code isn't recognized.
401 Unauthorized	Authentication failed: the token or subscription key is missing or invalid.
403 Forbidden	The token doesn't grant access to this tenant or operation, or the quota is used up.
404 Not Found	The tenant or resource doesn't exist.
409 Conflict	The request conflicts with existing data, such as a duplicate government identifier.
429 Too Many Requests	The rate limit was exceeded. See Rate limits.
500 Internal Server Error	Something went wrong on our side. Retry with backoff, and contact support if it continues.
502, 503, 504	The gateway or service is temporarily unavailable. Retry with backoff.

Validation errors (400)

When validation fails, the response includes an errors object that maps each field name (in camelCase) to one or more messages:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "firstName": ["'First Name' must not be empty."],
    "pageSize": ["Page Size cannot exceed 50"],
    "type": ["The specified certification type is not recognized."]
  }
}

Nested fields use dotted paths, such as homeAddress.postalCode. Show the messages to the user or log them. Your code can rely on the field names, but it shouldn't parse the message text, which may change.

Other problem responses

Other errors return a problem document without errors:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Conflict",
  "status": 409,
  "detail": "An agent already exists with the provided government identifier or tax ID."
}

When present, detail explains what went wrong. Responses may also include a traceId. Include it whenever you contact support.

Gateway errors

Errors raised by the API gateway itself, such as a missing subscription key, rate limiting or an exhausted quota, never reach the API. They use a simpler format:

{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 12 seconds." }

Handle both formats in your client.

Which errors to retry

Retry?	Statuses
Yes, with backoff	429, 500, 502, 503, 504, and network timeouts
Once, after getting a new token	401 caused by an expired token
No. Fix the request first	400, 403, 404, 409

See Best practices.