API errors
Most API problems come down to the key, the request shape, or an answer that is still running. These are the common cases and what to check.
Common issues
The
x-api-key header is missing (401 missing_api_key).The key is invalid, revoked, expired or from before workspace keys (401 with the code saying which).
The key is used on a route that is not the public API (403
api_key_route_not_allowed), or on another workspace (403 api_key_workspace_mismatch).The workspace has no prompts left (402
no_credits, with links to top-ups and pricing). Nothing was asked.Too many requests (429
rate_limited): more than 30 questions a minute from one key, or 8 waiting for that key, or 20 waiting in the workspace. Wait the Retry-After seconds; nothing was asked.Too many failed questions (429
too_many_failed_questions): 20 questions in an hour that used no prompt pause that key's new questions for up to an hour.The same
Idempotency-Key was sent with another question (409 idempotency_key_reused), or while the first request is still running (409 idempotency_request_in_progress: retry with the same key after Retry-After).Your client or Make timed out before STYD replied: the question keeps running and uses its prompt when it is answered. Retry with the same
Idempotency-Key, or find it with GET /api/v1/threads.The wrong workspace, thread, or run id was used.
The request body is missing a required field.
The request went to the wrong host or path.
The run is still queued or running, so the answer is not ready yet.
No plan is needed to use the API: only prompts. A question with a format (
json, text, email) costs the same 1 prompt.What to check
Verify the endpoint path —
https://speaktoyourdatabase.com/api/v1/… (GET /api/v1/context is the quickest check of a key).Read the
error code and the message of the JSON body: every refusal has both.Verify your key — it is shown once when created, so confirm it was copied and stored securely.
Generate, revoke, or rotate the key if it may be wrong or exposed.
After a queued or running response, poll
GET /api/v1/runs/{runId}?wait=30 until the status is complete or failed.Retry a timed-out call with the same
Idempotency-Key: the question is never asked twice.Use placeholders in examples and never paste a real key anywhere shared.
Test in a non-critical workspace first.
The API has no webhooks: STYD does not call you back. Ask, then poll
GET /api/v1/runs/{runId}.Every error code, with its status and what to do, is in the API reference; the getting-started guide has a first call with curl, JavaScript and Python, and the limits.