API errors
Every error response has a stable code, plus a message and hint written for the request that failed. Codes never change meaning; messages and hints may be reworded.
400 Bad Request
invalid_request
A parameter is missing or not valid. errors lists a message for each parameter to fix, such as {"end": ["The range can cover at most 92 days; this one covers 120."]}.
report_too_large
The summary report would have more than 5,000 rows. Request a shorter date range, group by fewer dimensions, or use a coarser period such as week instead of day.
mixed_currencies
The report covers accounts with different currencies, so their sales values can’t be added up. Filter by account, or add account or container to group_by.
invalid_idempotency_key
The Idempotency-Key header is empty or longer than 255 characters. Send a new random value, such as a UUID, for each distinct request.
401 Unauthorized
unauthenticated
No API key was sent. Send it in the Authorization header: Authorization: Bearer lts_….
invalid_api_key
The key is wrong, has been revoked, or belongs to someone whose login is disabled. Check the key was copied in full, and create a new one on the Developers page if needed.
invalid_token
The OAuth access token has expired, or the app was disconnected. Apps refresh expired tokens on their own; if this keeps happening, connect the app again.
403 Forbidden
missing_scope
The key doesn’t have the scope this endpoint needs, such as leads:read for individual leads. Create a key with that scope; scopes can’t be added to an existing key. For an app connected with OAuth, connect it again and allow that access on the consent screen.
forbidden
The key can’t access this resource.
404 Not Found
not_found
Nothing exists at this path, or the key can’t see it, for example a container in an account the key isn’t allowed to read. Check the path and any IDs in it.
405 Method Not Allowed
method_not_allowed
The endpoint doesn’t accept this HTTP method. Reporting endpoints only accept GET.
406 Not Acceptable
not_acceptable
The request’s Accept header rules out JSON. Accept application/json.
415 Unsupported Media Type
unsupported_media_type
A request body was sent in a format other than JSON. Send JSON with Content-Type: application/json.
409 Conflict
idempotency_key_in_progress
A request with this Idempotency-Key is still running. Retry after it finishes to get its response.
422 Unprocessable Entity
idempotency_key_reused
This Idempotency-Key was already used for a different request. Send a new key for each distinct request, and reuse one only to retry.
429 Too Many Requests
rate_limited
The key has made too many requests (60 a minute or 10,000 a day), or more than 20 requests a second came from your IP address. Wait the number of seconds in the Retry-After header, then retry.
too_many_concurrent_requests
Three requests are already running for this person, across all their keys. Wait for earlier requests to finish, or send fewer in parallel.
500 Internal Server Error
internal_error
Something went wrong on our side, and we’ve been notified. Retry later; if it keeps happening, contact us.
503 Service Unavailable
query_timed_out
The request took too long and was cancelled. Request a shorter date range.
