Publisher Offers V2 API errors
Most Offers V2 routes return a structured error body:
{
"code": "sdk_session_expired",
"message": "sdk_session_expired",
"fieldErrors": {},
"traceId": "trace_safe_identifier",
"retryable": false
}
A rate-limited response is 429, includes Retry-After, and may include retryAfterSeconds. Do not retry a non-retryable validation, authorization, or idempotency conflict unchanged. Keep the traceId for support; never attach a token or raw user record.
| Status / code family | Meaning | Recovery |
|---|---|---|
401 authentication_required, sdk_session_expired | Missing, invalid, or expired token | Use the correct credential type; create a fresh session when expired |
403 sdk_identity_mismatch, sdk_version_too_old, sdk_consent_required | Session does not satisfy placement rules | Correct identity, SDK version, or consent state |
403 placement_not_verified, placement_not_released | Review or production release incomplete | Finish review and coordinate release |
404 not_found | Feature disabled or resource unavailable | Check account/environment capability and ID scope |
404 no_fill | No eligible offer for this context | Show an empty state; do not fabricate inventory |
409 idempotency_conflict | A key was reused with different request content | Keep a key stable per logical write and use a new key for a new action |
429 rate_limited | Request budget exceeded | Honor Retry-After and back off |
Dashboard console, SDK, Static API, and callback credentials have separate scopes. A token that works for one family is not a fallback for another.