API problems

What each failing status code means in practice, and how to find the cause quickly.

Before you start

  • The requestId from the failing response — it is the fastest route to an answer
  • Confirmation that GET /v1/me succeeds with the same key
Triage

Start with /v1/me

If this fails, the problem is the key or the header — not the endpoint you were actually calling.

curl -sS https://api.simcoai.co.uk/v1/me \
  -H "X-SIMCOAI-API-Key: $SIMCOAI_API_KEY"
Codes

By status code

SYMPTOM401 Unauthorized

Usually because: Missing key, wrong header name, or a revoked key.

Fix: The header is X-SIMCOAI-API-Key exactly. Confirm the key is still active in your dashboard.

SYMPTOM403 Forbidden

Usually because: The key is valid but lacks the scope for that call.

Fix: Scopes are read, write and chat:write. Check the required scope on the API overview and issue a key that has it.

SYMPTOM404 Not Found

Usually because: No record with that id on your account, or an unsupported table name.

Fix: Tables are orders, refunds, bookings, escalations. Do not retry a 404 — it will not become a 200.

SYMPTOM409 WORKFLOW_DUPLICATE

Usually because: The work already exists. This is duplicate protection doing its job.

Fix: Treat it as success. See idempotency. Retrying is the wrong response and confuses the customer.

SYMPTOM422 Unprocessable

Usually because: A required field is missing. Orders need order_number; escalations need reason.

Fix: Read details.code — it names the exact field.

SYMPTOM429 Too Many Requests

Usually because: You exceeded the rate limit, usually via a retry loop or per-record polling.

Fix: Back off exponentially with jitter and cap your retries. See rate limits.

Reporting

What to send us

The requestId, the endpoint and method, roughly when, and what you expected. Never send us a live secret key — if one has been exposed, revoke it first.