Error Handling

All Avaya Infinity™ APIs return errors using the RFC 7807 Problem Details format, served with the application/problem+json content type.

Response format

Field	Type	Description
`type`	string (URI)	Identifies the problem type. Dereferencing it should lead back to this page, at the matching anchor below.
`title`	string	Short, human-readable summary of the problem type. Not localized.
`status`	integer	The HTTP status code for this occurrence of the problem.
`detail`	string	Human-readable explanation specific to this occurrence.
`instance`	string (URI)	Optional. Identifies the specific occurrence of the problem.
`violations`	array	Present on validation errors (400, 422). See Violations below.
`requestId`	string	Correlation ID for this request. Include this when contacting support.
`timestamp`	string (date-time)	When the error was generated.
`retryAfter`	integer	Seconds to wait before retrying. Present only on 429 and 503 responses.

Violations

When a request fails validation, violations lists every field-level problem found:

Field	Type	Description
`field`	string	The path parameter, query parameter, or request body field that caused the violation.
`message`	string	Human-readable explanation. This text can change; don't match on it in error-handling logic.
`code`	integer	Stable violation code. Use this for programmatic error handling instead of `message`.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#constraint-violation",
  "title": "Constraint Violation",
  "status": 400,
  "detail": "Request contains invalid or missing fields",
  "violations": [
    { "field": "accountId", "message": "must match \"^[a-zA-Z]{6}$\"", "code": 20006 }
  ]
}

Status codes

Constraint Violation

HTTP Status: 400 Bad Request

The request is malformed or fails validation.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#constraint-violation",
  "title": "Constraint Violation",
  "status": 400,
  "detail": "Request contains invalid or missing fields",
  "violations": [
    { "field": "accountId", "message": "must match \"^[a-zA-Z]{6}$\"", "code": 20006 }
  ]
}

Unauthorized

HTTP Status: 401 Unauthorized

The request has no valid authentication credentials, or the token has expired.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Bearer token expired at 2025-12-08T10:15:00Z. Request a new token.",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z"
}

Forbidden

HTTP Status: 403 Forbidden

The authenticated caller does not have the required role or scope for this operation.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing required scope: 'workflows:execute'. Your token has: 'workflows:read'",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z"
}

Not Found

HTTP Status: 404 Not Found

The requested resource doesn't exist, or the URL path doesn't match any known API method.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "workflowId 'wf_123abc' does not exist",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z"
}

Method Not Allowed

HTTP Status: 405 Method Not Allowed

The HTTP method isn't supported for this endpoint. The response includes an Allow header listing supported methods.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#method-not-allowed",
  "title": "Method Not Allowed",
  "status": 405,
  "detail": "POST method is not supported for this endpoint. Allowed methods: GET, PUT",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z"
}

Conflict

HTTP Status: 409 Conflict

The request conflicts with the current state of the resource, typically a uniqueness constraint.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A resource with the same unique constraint values already exists",
  "violations": [
    { "field": "name", "message": "A category with this name already exists", "code": 20000 }
  ]
}

Validation Failed

HTTP Status: 422 Unprocessable Entity

The request is well-formed and passes basic constraint checks, but fails a business rule (for example, a limit tied to account or license configuration).

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Profile User limit of 500 reached. Cannot update profile",
  "violations": [
    { "field": "profileId", "message": "Profile User limit of 500 reached. Cannot update profile", "code": 20005 }
  ]
}

Rate Limit Exceeded

HTTP Status: 429 Too Many Requests

The caller has exceeded a rate limit. The response includes a Retry-After header and a matching retryAfter body field, in seconds.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have made 1,050 requests in the last minute. Limit: 1,000 requests per minute",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z",
  "retryAfter": 45
}

Internal Error

HTTP Status: 500 Internal Server Error

An unexpected condition prevented the server from fulfilling the request. If this persists, contact support with the requestId.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z"
}

Service Unavailable

HTTP Status: 503 Service Unavailable

The service is temporarily unable to handle the request, typically due to load. The response includes a Retry-After header and matching retryAfter body field.

{
  "type": "https://developers.avayacloud.com/avaya-infinity/docs/errors#service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service is experiencing high load. Please retry in 30 seconds",
  "requestId": "req_xyz789",
  "timestamp": "2025-12-08T10:30:05Z",
  "retryAfter": 30
}

Known violation codes

Codes observed in current API specs and examples. This list reflects what's documented today, not a complete registry; confirm with engineering before treating it as exhaustive.

Code	Meaning
20000	Uniqueness conflict (a resource with the same constraint value already exists)
20002	Required field is null or missing
20005	Profile user limit reached (500 users)
20006	Field value doesn't match the required pattern
20008	Invalid email format

Handling rate limits and retries

Check for a Retry-After header (seconds) on 429 and 503 responses, or the equivalent retryAfter field in the response body.
Use exponential backoff for repeated 5xx errors.
Include the requestId from an error response when contacting support about that specific occurrence.