Error Codes & Troubleshooting
This page describes how errors are returned by the BaseQR API, the most common causes, and practical steps to resolve them.
Error response format
• Structure — Errors return JSON with a stable envelope.
Example:{ "error": { "code": "string", "message": "human-readable description", "details": { ... } } }
• Fields —
o code — Short, machine-friendly identifier (for example, invalid_argument, not_found).
o message — Actionable description.
o details — Field-level validation info or context when available.
Common HTTP statuses
• 400 Bad Request — Invalid payload or parameters (malformed JSON, wrong types, missing required fields).
• 401 Unauthorized — Missing or invalid API key; Authorization header absent or malformed.
• 403 Forbidden — Authenticated, but the key lacks permission for the attempted action (Admin-only operation with a User key).
• 404 Not Found — Resource does not exist or is not accessible in your organization.
• 409 Conflict — Duplicate create due to reusing an idempotency/client reference or conflicting state.
• 422 Unprocessable Entity — Well-formed request that fails semantic validation (for example, invalid URL, UTM formatting issues).
• 429 Too Many Requests — Rate limit exceeded; slow down and retry with backoff.
• 5xx Server Error — Temporary issue on our side; safe to retry with backoff.
Troubleshooting checklist
• Auth — Is the Authorization header present and correctly formatted? Are you using the correct environment and a current key with sufficient permissions?
• Payload — Is the JSON valid? Are all required fields present and spelled exactly as documented?
• Permissions — Does your key have organization-level access for this resource and action (Admin vs. User)?
• Rate limit — Check response headers if provided; add exponential backoff and idempotency on create calls.
• Network — Ensure HTTPS/TLS is used end-to-end; confirm proxies or gateways are not stripping headers.
• Redirects — If destinations redirect, verify the final URL remains valid and UTMs persist across hops.
• Support — When opening a ticket, include the request ID (if available), UTC timestamp, endpoint, status code, and a minimal sample payload (omit secrets).
Troubleshooting by symptom
• Authentication fails (401) —
o Header — Verify Authorization header format and presence on every request.
o Key — Confirm the key is active and copied exactly (no whitespace). Use server-side calls only.
• Permission denied (403) —
o Role — Some actions are Admin-only (invites, role changes, deletes). Use an Admin key.
o Org context — Keys are scoped to one organization.
• Validation error (400/422) —
o Destination URL — Must be valid HTTPS and reachable on mobile.
o UTMs — Lowercase keys, no spaces; expected fields only (utm_source, utm_medium, utm_campaign, optional utm_content, utm_term).
o Bulk CSV — Match the Bulk Import Template (column names, UTF-8, single header row).
• Resource not found (404) —
o IDs — List campaigns/codes first and use returned IDs; avoid hard-coding stale IDs.
o Cross-org — An ID from another org will not resolve.
• Conflicts or duplicates (409) —
o Idempotency — Reuse the same client reference only when retrying the same create; otherwise generate a new value.
o Bulk imports — De-duplicate rows before upload.
• Rate limit exceeded (429) —
o Backoff — Implement short exponential backoff and jitter.
o Batching — Reduce request bursts; consolidate operations where appropriate.
o Idempotency — Protect create retries from duplicating data.
• Export/report failures —
o Formats — Use supported types (SVG/PNG/JPG for assets; CSV/XLSX/PDF for reports).
o Scope — Ensure filters (date range, campaign) match your intent; export code data from code context.
Diagnostic checklist
• Reproduce minimally — Re-run with only required fields to isolate the failing parameter.
• Compare to a known-good call — Use a previously successful request as a control.
• Validate inputs locally — Check URL syntax and JSON structure before sending.
• Service status — If simple calls fail repeatedly, review Uptime Status before escalating.
Retry guidance
• Safe to retry — 5xx and 429 responses, or transient network errors. Use exponential backoff and (on creates) a stable idempotency/client reference.
• Do not retry — 400/403/404/422 until inputs, roles, or resource IDs are corrected.
When to escalate
• Include — Endpoint, UTC timestamp, request ID (if available), HTTP status, and minimal request/response snippets (omit secrets).
• Describe impact — Note whether the issue affects one resource or multiple endpoints and whether it’s blocking production.
Best practices
• Validate before send — Enforce basic URL and UTM checks client-side to prevent avoidable 4xx errors.
• Small, verifiable batches — For bulk operations, import a subset first, verify, then scale.
• Log and monitor — Capture non-2xx responses with context; alert on repeated failures.
• Keep conventions stable — Consistent naming and UTMs simplify reconciliation with GA4.