HTTP status codes

Use the HTTP status code as the primary indicator of the overall request outcome.

Code	Description	How to handle it
`200 OK`	Request completed successfully.	Process normally. Valid list requests with no matches return an empty result set.
`201 Created`	A resource was created successfully.	Process the created resource or returned identifier.
`202 Accepted`	An asynchronous request was accepted but is not complete.	Use returned job/status information to check completion.
`204 No Content`	Request completed successfully with no response body.	Treat as success; do not parse a body.
`206 Partial Content`	Only part of the requested content is available.	Process returned content and inspect unavailable content.
`207 Multi-Status`	A bulk request contains mixed item-level outcomes.	Evaluate each item independently; do not treat the entire response as failed.
`400 Bad Request`	Malformed request or request/field validation failure.	Use error information to correct the request before retrying.
`401 Unauthorized`	Authentication is missing, invalid, or expired.	Obtain valid authentication and retry.
`403 Forbidden`	Caller is authenticated but lacks required access.	Verify access; do not retry unchanged unless access changes.
`404 Not Found`	Requested resource does not exist or is not accessible.	Verify the resource identifier or path.
`409 Conflict`	Request conflicts with resource state, readiness, or uniqueness.	Resolve the conflicting condition before retrying.
`410 Gone`	A previously valid resource is permanently unavailable or expired.	Do not retry the same resource reference.
`429 Too Many Requests`	API rate limit has been exceeded.	Honor `Retry-After` and use backoff.
`500 Internal Server Error`	Unexpected server-side failure.	Retry when appropriate for the operation and use backoff. Follow the support process if the issue persists.
`503 Service Unavailable`	The service is temporarily unavailable, overloaded, or undergoing a transient disruption.	Retry with backoff when the operation is safe to retry. Honor `Retry-After` when it is returned.
`520`	The gateway received an unexpected or unrecognized response from an upstream service.	Treat as a transient infrastructure failure. Retry with backoff when the operation is safe to retry.
`521`	The gateway could not establish a connection to the upstream service.	Treat as a transient infrastructure failure. Retry with backoff when the operation is safe to retry.

Error Handling

When an API returns an error, first use the HTTP status code to determine the type of failure. Then inspect the response body for additional information about what failed.

Error responses can include the following fields:

Field	Description
`code`	Indicates the outcome of the request or item, such as `success` or `failure`.
`details`	Machine-readable result or error codes. Use these codes for programmatic error handling.
`message`	Optional high-level, human-readable summary of the error.
`errors`	Structured diagnostics for a failed item. When present, use `errorType` for the error condition, `field` for the affected request field when applicable, and `description` for an explanation of the error and, when available, guidance on how to resolve it.

Example error response

{ "code": "failure", "details": ["ERROR_CODE"], "message": "One or more errors occurred.", "errors": [ { "field": "fieldName", "errorType": "ERROR_CODE", "description": "Explanation of the error and, when available, how to resolve it." }
]
}

Exact fields can vary by endpoint and error condition. See the endpoint's API Reference for the complete response schema.

Bulk and partial responses

Some APIs process multiple items in a single request. When a bulk request returns mixed outcomes, evaluate each item in the response independently. Successful items contain the fields defined for that endpoint's successful response, while failed items include error information describing the individual failure.

Do not treat a mixed-outcome response as a failure of every item. Process successful items normally and use the error information returned for failed items to determine the appropriate next action.

Response schemas vary by endpoint. See the endpoint Guide for workflow-specific response behavior and examples, and the API Reference for the exact response fields and schema.

Retry guidance

Response	General guidance
`400`, `403`, `404`, `410`	Do not retry unchanged. Correct the request, access, or resource reference first.
`409`	Retry only after the conflicting state or condition changes.
`429`	Wait for the `Retry-After` duration before retrying.
`5xx`, including `503`	Retry with backoff when the operation is safe to retry. Honor `Retry-After` when provided.
`520`, `521`	Treat as transient infrastructure failures and retry with backoff when the operation is safe to retry.

API Reference

This guide describes common behavior across Display APIs. For an endpoint's exact supported HTTP responses, response schema, field types, optionality, and examples, see that endpoint in API Reference.