Errors & Debugging
Failure modes, retries, and troubleshooting
Use this section to diagnose integration failures quickly and verify production-safe SDK behavior.
Common failures
| Issue | Likely cause | Recommended fix |
|---|---|---|
| 401 Unauthorized on ingest | Missing or invalid x-api-key header. | Check key value, prefix, and whether key is enabled. |
| 403 Organization mismatch | Event organizationId differs from key metadata organizationId. | Set SDK organizationId to the exact org from Dashboard settings. |
| Client SDK throws before initialization | window.openai is not available in runtime context. | Initialize in ChatGPT widget runtime where window.openai exists. |
| 429 Too Many Requests | Rate limit exceeded. | Back off, respect retryAfter, reduce burst volume. |
| Events accepted but metrics missing | Normalization/aggregation lag or wrong org scope. | Verify organizationId, inspect processor status, re-check time range filters. |
| CORS or network errors from browser | Endpoint not allowing request origin/headers. | Confirm CORS setup includes Content-Type and x-api-key headers. |
Retry strategy (factual)
- - Server SDK exporter retries failed sends up to 3 attempts.
- - Client SDK exporter retries failed sends up to 3 attempts.
- - Both use exponential backoff with jitter (base 500ms, max delay 5s).
- - development environment logs emitted events to console.
Debugging checklist
- 1Confirm endpoint is reachable from your runtime (server or browser).
- 2Confirm API key is valid, enabled, and belongs to the target organization.
- 3Confirm SDK organizationId matches key metadata organizationId.
- 4Confirm event payload matches ingest schema and required fields.
- 5Confirm CORS headers allow Content-Type and x-api-key if calling from browser.
window.openai requirement
The client SDK throws if
window.openai is unavailable. Initialize only in the ChatGPT widget runtime.Rate limit handling
Respect
retryAfter on 429 responses and reduce burst volume.