Common Error Codes

Every failure in the Headless API is designed to be diagnosable from two things: the HTTP status and the error string in the body. This page collects all of them in one place, with fixes.

---

The error envelope

• Every error response is JSON with an error string: { "error": "..." }.
• Some errors add fields: retry_after (rate limit), message and reason (start-endpoint availability errors), current and limit (quota errors), closed (paused studies).
• There is no code or details field. Match on the HTTP status and the error string.
• The message endpoint can also fail mid-stream: the final SSE frame is then {"type":"error","error":"Stream processing failed"} with the HTTP status already committed as 200.

A typical error body:

{
  "error": "Rate limit exceeded",
  "retry_after": 42
}

---

Status code overview

---

Every error string

This table consolidates every distinct error the API returns, across the start, message, complete, read, and embed bootstrap endpoints. The four per-permission 403s are collapsed into one row: the real string names the specific scope, for example API key does not have interview:read permission.

Per-endpoint error tables, including which extra fields accompany each error, live on the endpoint pages: Starting Interviews, Sending Messages, and Completing Interviews.

---

SSE stream errors

The message endpoint streams its reply as Server-Sent Events, which means a failure can happen after the HTTP status is already committed as 200. In that case the last frame of the stream is:

data: {"type":"error","error":"Stream processing failed"}

Your SSE parser must treat an error frame as terminal for that message. Do not rely on the HTTP status alone for the message endpoint; check frame types. See Sending Messages via API for a parser that handles this correctly.

---

Debugging checklist

• Key rejected? Confirm it starts with pk_live_, is active (not revoked), and hasn't expired.
• Invalid session token? Send the exact session_token from the start response in the X-Session-Token header, for the same interview id.
• Origin not allowed? Your key restricts origins; add your site's origin (with scheme) or use a wildcard entry.
• Interview is not active? The interview was already completed. Start a new one.
• Missing permission? The key was created with a narrowed permission set; create a key that includes the scope you need.
• 429? Check retry_after and the X-RateLimit-* headers; distinguish rate limits from interview_limit_reached quota errors.

---

FAQ

Is there an error code field I can switch on?

No. There is no code or details field. Match on the HTTP status plus the error string. The strings in the table above are the exact strings the handlers return.

I got a 429. Should I retry?

Depends on the string. Rate limit exceeded resolves after retry_after seconds. interview_limit_reached is a quota error and retrying will not help. See Rate Limits and CORS.

Why do I get 401 on message but 200 on start with the same key?

Start needs only the API key. Message additionally needs the X-Session-Token header with the exact token from the start response. A missing or mismatched token fails with 401 even though the key is valid.

The error says the interview belongs to a different project. What happened?

Interview ids are study-scoped, and so are API keys. You are calling with a key from one study and an interview id from another. Use the key for the study that owns the interview.