Handle API errors

Check the HTTP status and response body. Successful responses use ok: true and place the result in data. Errors use this shape:

{
	"ok": false,
	"error": {
		"code": "CONFLICT",
		"message": "offer is used by rotators",
		"details": {
			"blocked": ["OFFER_ID"]
		}
	},
	"requestId": "REQUEST_ID_IF_AVAILABLE"
}

Use error.code to handle failures in your application and error.message to explain them. details and requestId are optional.

Choose the next action by failure type

Status	Typical cause	Next action
`400`	Invalid request	Correct the request using the endpoint reference
`401`	Authentication failed	Verify the key with whoami
`402`	Public API subscription access is unavailable	Check Subscription
`403`	Access denied	Check the key’s scope and use a server-side request
`404`	Entity or endpoint not found	Check the ID, workspace, method, and path
`409`	A conflict prevents the change	Follow the error message before retrying
`413`	Request body exceeds the endpoint limit	Reduce the payload
`422`	Supported limits exceeded	Follow the endpoint’s limits or simplify the request
`429`	Too many requests or an event query is too broad	Back off or narrow the query, depending on the error code
`500` or `503`	The service is temporarily unavailable	Retry a read with backoff and keep diagnostic context

Retry a request

For RATE_LIMITED, wait for Retry-After when supplied. Otherwise, wait progressively longer between retries and limit the number of attempts. For SCROLL_BUDGET_EXCEEDED or REPORTS_QUERY_TOO_EXPENSIVE, shorten the date range or filter to a campaign before starting a new query. A BAD_CURSOR needs a new event query without the old cursor. After a timeout during a write, check whether the change was saved before repeating the request. This avoids creating duplicate entities.

Get help

Include the method, endpoint, status, error code, and request ID when available. For report issues, include the date range and timezone. Leave API keys and Authorization headers out of logs and support messages.

Use the API

Endpoints

Choose the next action by failure type

Retry a request

Get help

​Choose the next action by failure type

​Retry a request

​Get help

Choose the next action by failure type

Retry a request

Get help