SaaS Troubleshooting & FAQ Guide

Troubleshooting and FAQ Guide — SaaS Platform

Find the error, fix it in minutes, stop it coming back. For developers, support engineers, and product teams integrating with the platform API.

How to use this guide

Find your error code in the error list below. Each entry gives the root cause, the immediate fix, and the prevention step. If your error is not listed, use the FAQ section, then follow the support checklist.

Severity key: Blocking — requests fail entirely. Degraded — some requests fail or slow down. Warning — works now, will fail later if ignored.

What you need: your API key, the exact error message (copy it, don't paraphrase it), and the request ID from the response headers (X-Request-ID).

Before you start

Read the error before you fix anything. Every response from the platform includes three things: the HTTP status code (for example 401, 429, 500), the error body (for example: error "invalid_token", message "API key expired"), and the request ID in the response headers.

Tip: Copy the full error body into your notes before you retry. Retrying without the original message destroys the one piece of evidence that tells you what actually went wrong.

The 60-second triage

Ask these four questions first:

Did this exact request work before? If yes, something changed — check your key, your payload, or the platform status page first.

Is it failing for every request, or just some? Every request means your credentials or configuration. Some requests means your payload or rate limits.

Is the platform status page showing an incident? If yes, stop troubleshooting your code. Wait for the incident to clear, then re-test.

Did you just deploy or rotate a key? The last change is the prime suspect. Roll it back and test again.

Warning: Never paste a live API key into a support ticket, a chat message, or a public forum. Share only the first 8 characters and the request ID. Support can find everything else from those two.

Error list

Authentication and authorization

401 Unauthorized — invalid_token. Severity: Blocking. Symptom: every request rejected; "Authentication failed". Root cause: API key expired, revoked, or copied with a typo or trailing space. Immediate fix: generate a new key in Settings, then API Keys; replace it in your config; re-test one request. Prevention: store keys in a secrets manager, never in code; set a calendar reminder 7 days before expiry; rotate keys on a schedule.

401 Unauthorized — invalid_signature (webhooks). Severity: Blocking. Symptom: webhook receiver rejects every delivery. Root cause: signing secret mismatch, or the signature was computed over the wrong payload. Immediate fix: re-copy the signing secret from Settings, then Webhooks; verify you sign the raw request body, not the parsed JSON. Prevention: pin the secret in one place; add a signature check to your deployment checklist.

403 Forbidden — insufficient_scope. Severity: Blocking. Symptom: auth works, but a specific endpoint returns 403. Root cause: key lacks the scope that endpoint requires (for example write versus read). Immediate fix: in Settings, then API Keys, add the missing scope to the key, or create a scoped key for that job. Prevention: document required scopes next to each endpoint in your integration notes; use least-privilege keys per service.

401 Authentication Timeout. Severity: Degraded. Symptom: requests hang, then fail with a timeout during login or token exchange. Root cause: auth server slow to respond, network latency, or an expired token being refreshed in a loop. Immediate fix: retry once with a 30-second timeout; if it persists, check the platform status page, then re-authenticate from scratch. Prevention: cache tokens until 5 minutes before expiry instead of refreshing on every request; add a circuit breaker after 3 failed refreshes.

Request errors

400 Bad Request — validation_failed. Severity: Degraded. Symptom: request rejected; response names a field. Root cause: missing required field, wrong data type, or malformed JSON. Immediate fix: read the details array in the error body — it names the exact field; fix that field and resend. Prevention: validate payloads against the API reference before sending; add a schema check in your test suite.

404 Not Found — resource_not_found. Severity: Degraded. Symptom: a specific ID returns 404 while others work. Root cause: wrong endpoint URL, a deleted resource, or an ID from the wrong environment (test versus live). Immediate fix: confirm the ID exists in the same environment (test key goes with test data, live key goes with live data); check for typos in the URL. Prevention: keep test and live IDs in separate config files; never hardcode IDs.

408 Request Timeout. Severity: Degraded. Symptom: request hangs past 30 seconds, then fails. Root cause: large payload, slow query, or a congested network path. Immediate fix: reduce the payload or split the request; retry once with exponential backoff. Prevention: set client timeouts to 30 seconds and retry with backoff; page large result sets instead of fetching everything at once.

Rate limits and server errors

429 Too Many Requests — rate_limit_exceeded. Severity: Degraded. Symptom: requests start failing after a burst; Retry-After header present. Root cause: you exceeded the plan's request limit (requests per minute or per day). Immediate fix: stop sending; wait the number of seconds in the Retry-After header; then resume at half speed. Prevention: read X-RateLimit-Remaining on every response; queue requests and spread them out; cache repeated reads; upgrade the plan if you sit near the limit daily.

500 Internal Server Error. Severity: Blocking. Symptom: random requests fail with no useful message. Root cause: a fault on the platform side. Immediate fix: retry once after 60 seconds with backoff; if it repeats, check the status page and open a support ticket with the request ID. Prevention: log every 500 with its request ID; alert on more than 5 in 10 minutes — a spike usually means a platform incident, not your code.

502 Bad Gateway / 503 Service Unavailable. Severity: Blocking. Symptom: all requests fail for minutes at a time. Root cause: upstream service down, or a deploy in progress. Immediate fix: wait and retry with backoff (60 seconds, then 120, then 300); do not hammer the endpoint. Prevention: build a queue so failed requests retry automatically later instead of being lost; show users a "try again shortly" message.

Webhook delivery failures

Webhook delivery failed — retries exhausted. Severity: Blocking. Symptom: events stop arriving; dashboard shows failed deliveries. Root cause: your endpoint is down, returns a non-2xx status, or takes longer than 10 seconds to respond. Immediate fix: fix the endpoint, then use Webhooks, then Deliveries, then Redeliver to replay the missed events. Prevention: respond 200 OK immediately and process the event asynchronously; keep response time under 2 seconds.

Webhook endpoint returns 404/405. Severity: Blocking. Symptom: every delivery fails instantly. Root cause: wrong URL in the webhook settings, or the endpoint only accepts GET. Immediate fix: correct the URL in Settings, then Webhooks; confirm the endpoint accepts POST. Prevention: test the endpoint with a manual POST before saving it; add the webhook URL to your deployment checklist.

Webhook events arrive duplicated. Severity: Warning. Symptom: same event processed twice. Root cause: a retry fired after your endpoint responded slowly, or the platform re-sent after a timeout. Immediate fix: make your handler idempotent — store the event ID and skip it if already processed. Prevention: always store and check the event ID before acting on a webhook; never assume one delivery per event.

Frequently asked questions

Q: I keep getting 401, but my key is correct. What else could it be?

A: Three things cause this even with a good key. First, a trailing space or newline copied with the key — paste it into a plain-text editor and check both ends. Second, you are using a test key against the live API, or vice versa. Third, the key was revoked when a teammate rotated keys. Generate a fresh key and test with curl before changing your code.

Q: How do I know if the problem is mine or the platform's?

A: Check the platform status page first. Then send the same request from a different network or machine. If it fails everywhere, it is the platform. If it works elsewhere, the problem is your environment — proxy, firewall, or DNS.

Q: My requests work in testing but fail in production. Why?

A: Almost always one of three differences: the production key has different scopes, the production environment has a stricter firewall, or the production payload contains real data that breaks validation (special characters, longer strings, empty fields). Diff your test and production configs line by line.

Q: Should I retry a failed request?

A: Retry 429s, 500s, 502s, and 503s with exponential backoff (wait 1 second, then 2, then 4, up to 5 attempts). Never automatically retry 400s or 401s — those will fail identically every time, and retrying a 400 that creates a record can create duplicates.

Q: A webhook fired, my endpoint returned 200, but nothing happened. What now?

A: Your endpoint accepted the event but your handler dropped it. Check your handler logs for the event ID, confirm the event type matches what your code listens for, and verify your idempotency check is not silently skipping it.

Q: How fast should my API client retry after a 429?

A: Exactly as fast as the Retry-After header says — no faster. If the header says 30 seconds, wait 30 seconds. Retrying early resets the wait and can extend the block.

Contacting support — what to include

If the list above does not resolve the issue, open a ticket with everything below. Tickets with all five items are resolved measurably faster than tickets without them.

Exact error — status code plus full error body. Example: 401, error "invalid_token", message "API key expired".

Request ID. Example: X-Request-ID: req_8f2k1n9q.

When it started — first failure time plus timezone. Example: 2026-11-07 09:14 EST.

What changed — deploys, key rotations, config edits. Example: rotated API key at 09:00 EST.

What you already tried. Example: generated a new key; tested with curl; same 401.

Note: Include the first 8 characters of your API key only. Never send a full key. Support does not need it, and a ticket is not a secure place for one.

Prevention checklist — run monthly

Review API key expiry dates; rotate any key older than 90 days.

Confirm webhook endpoints still return 200 in under 2 seconds.

Check X-RateLimit-Remaining on your busiest integration — if it regularly drops below 10 percent, plan a higher tier or add caching.

Verify your retry logic uses exponential backoff and caps at 5 attempts.

Confirm your webhook handler stores event IDs and skips duplicates.

Re-read the platform changelog for deprecated endpoints or scope changes.

Sample documentation prepared as a portfolio piece. Error messages, request IDs, and platform names are fictional examples. Always confirm current rate limits, timeouts, and status-page URLs against the live platform documentation.