Troubleshooting
Find the first failing step. Keep model generation available while you diagnose the separate ad path.
Check in order
| publicOrigins | Exact HTTPS origins, plus explicit loopback HTTP for local development | Required nonempty list, no wildcard | Dashboard verified origins / local server ENV |
|---|---|---|---|
| Symptom | Check | Next action | |
| Setup warning or no code to copy | Saved HTTPS app URL, verified exact origin, selected project and package | Complete this project's settings. Do not copy incomplete snippets. | |
| 401 / authentication_required | Your app session and the key class/project | Connect the real authentication and session hooks. Reauthenticate only when the session actually expired. | |
| 403 | Fixed reason for origin, consent or policy rejection | Match the exact origin and current real consent. Preserve GPC. Never strip a denied signal. | |
| 400 / validation_error | Reported field path and installed package version | Correct the field, format or version. Do not retry the same invalid request. | |
| 429 | Retry-After and client retry count | Back off. Do not parallelize retries or retry a completed turn. | |
| No-Fill | decision.fill, current consent, requested formats and generation phase | Keep the slot empty and model output usable. No-Fill is not a broken installation. | |
| Fill but no visible ad | Renderer script, frame navigation, ready milestone and geometry | Trace the frame before changing CSS or timing. HTTP 200 does not prove presentation. |
Frame diagnostics
Read frame_load_error or frame_timeout before your app removes the slot. Record only fixed stage/reason names, relative timings and the matching turn/request/slot IDs.
Distinguish script loading, iframe response, navigation commit, ready event, cleanup and actual visible creative. A hidden slot after frame cleanup is not proof of an ad blocker.
If the observer cannot expose a browser navigation milestone, record it as unknown. An empty console does not prove success. Reproduce with a harmless local frame before repeating a real generation.
Do not export raw HAR, signed frame URLs, headers, cookies, bodies, prompts or credentials. Do not loosen CSP, extend timeouts or delay the model merely to make a check pass.
Delivery limits
frequency_cap_exceeded means the configured session limit was reached. Check the app's delivery settings and wait for capacity. Do not rotate session identifiers or reset counters to bypass the limit.
frequency_session_required means your integration did not supply a stable app session. frequency_configuration_invalid means the saved limits need review. frequency_service_unavailable and frequency_context_unavailable are technical checks that could not finish, not proof that a user reached their limit.
Keep generation running without an ad. Use the recorded request reference when asking for help. A missing reset time is unknown, not permission to retry immediately.
App URL and origins
Save the full HTTPS app URL and the exact verified origins for the selected project. A value visible in an unsaved field is not an approved origin.
www.example.com and example.com are separate hosts. Paths belong to the app URL, not to an origin. Do not add wildcard origins or copy another project's domain proof.
Consent results
Consent synchronization records the app session's current choice. It does not count as a new user decision or an ad display. Inspect the result to distinguish a completed synchronization from a failed request.
For consent_not_current, connect the current session choice before requesting an ad. For consent_state_unavailable, keep the slot empty and retry later. Respect privacy_signal_policy_required and declined consent; do not remove browser privacy signals.
Common questions
For a key recovery, exact-origin or lifecycle problem, follow the focused answer rather than restarting the whole integration.
Need help with your integration?
Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.