Reference

Error codes

Errors should tell you what went wrong, what to do next, where to read more, and the request_id for support.

Envelope

JSON errors include an error code, message, docs_url when available, and request_id. The same request ID is returned in X-Request-Id.

Common codes

Runtime error codes are lowercase. unauthorized means add valid credentials, forbidden means use the correct key type or origin, and rate_limited means back off using Retry-After.

validation_error

validation_error means fix request body shape.

privacy_signal_policy_required

A positive Sec-GPC signal blocks new advertising admission (403). Preserve observed signals across backend hops and continue the primary app flow without ads; do not retry by stripping the signal.

not_found

not_found means the resource is missing or outside the authenticated scope.

Support

Include request_id, endpoint, key mode, and environment when asking for help. Never include full API keys.

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team