{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-05-18T13:46:14.434Z"},"content":[{"type":"documentation","id":"0b88ef82-b556-4015-8d53-e0c15e2fc798","slug":"common-error-codes","title":"Common Error Codes","url":"https://www.koji.so/docs/common-error-codes","summary":"Reference guide for Koji error codes. Covers authentication errors (401, 403), request errors (400, 404, 409, 422), rate limiting (429), server errors (500), and embed widget errors. Includes four API permissions: interview:start, interview:chat, interview:complete, interview:read.","content":"# Common Error Codes\n\nWhen something goes wrong in Koji -- whether through the API, the embed widget, or the dashboard -- you receive an error with a code and message. This reference explains what each error means and how to fix it.\n\n---\n\n## How Errors Are Structured\n\nKoji returns errors as JSON objects with a consistent structure:\n\n```json\n{\n  \"error\": \"error_code\",\n  \"message\": \"A human-readable description of what went wrong.\"\n}\n```\n\nThe `error` field is a machine-readable code you can use in your application logic. The `message` field provides a plain-language explanation.\n\nFor API errors, the HTTP status code also indicates the category of the problem.\n\n---\n\n## Authentication Errors (4xx)\n\nThese errors relate to API keys, session tokens, and account permissions.\n\n### 401 -- unauthorized\n\n**Message**: \"The provided API key is invalid or has been revoked.\"\n\n**Cause**: Your API key is missing from the request, is malformed, or has been revoked.\n\n**Fix**:\n- Check that the `Authorization` header is present and formatted as `Bearer your_api_key`.\n- Verify the key has not been revoked in **Dashboard > Profile > API Keys**.\n- Make sure you copied the full key without extra spaces.\n\nSee [API Authentication](/docs/api-authentication) for details.\n\n### 401 -- invalid_session_token\n\n**Message**: \"The session token is invalid or expired.\"\n\n**Cause**: The `X-Session-Token` header contains an invalid or expired token.\n\n**Fix**:\n- Use the session token exactly as returned by the start endpoint.\n- Session tokens are tied to a specific interview and expire after the interview is completed or timed out.\n- If the token has expired, you need to start a new interview.\n\n### 403 -- forbidden\n\n**Message**: \"Your API key does not have the required permission for this action.\"\n\n**Cause**: The API key exists and is valid, but it does not have the permission needed for the endpoint you are calling.\n\n**Fix**:\n- Check which permissions your key has in **Dashboard > Profile > API Keys**.\n- Add the missing permission. The four available permissions are: `interview:start`, `interview:chat`, `interview:complete`, and `interview:read`.\n\n### 403 -- feature_not_available\n\n**Message**: \"This feature is not available on your current plan.\"\n\n**Cause**: This error may appear if you are on an older account configuration. On current Koji plans, all features are available on every plan (Free, Insights, Interviews, Enterprise). Credits are the only gate.\n\n**Fix**:\n- If you see this error, try refreshing the page or logging out and back in.\n- Check your account status in **Account Settings > Billing**.\n- If the issue persists, contact support -- this error should not appear for active accounts on current plans.\n- See [plan comparison guide](/docs/plan-comparison-guide) for plan details.\n\n---\n\n## Request Errors (4xx)\n\nThese errors indicate problems with the request itself.\n\n### 400 -- invalid_request\n\n**Message**: Varies. Examples: \"The field project_id is required.\" or \"Invalid JSON in request body.\"\n\n**Cause**: The request body is missing required fields, contains invalid values, or has malformed JSON.\n\n**Fix**:\n- Check the endpoint documentation for required fields.\n- Validate your JSON syntax before sending.\n- Ensure all field types match what the API expects (strings, UUIDs, etc.).\n\n### 404 -- not_found\n\n**Message**: \"The requested resource was not found.\"\n\n**Cause**: The interview, project, or guide ID in your request does not match any existing resource.\n\n**Fix**:\n- Verify the ID is correct. UUIDs are case-sensitive.\n- Confirm the resource exists in the Koji dashboard.\n- Check that the resource belongs to the project your API key is scoped to.\n\n### 409 -- conflict\n\n**Message**: Varies. Example: \"This interview has already been completed.\"\n\n**Cause**: The action you are trying to perform conflicts with the current state of the resource.\n\n**Fix**:\n- For \"already completed\" errors, this is usually benign -- the interview was completed previously.\n- Check the resource's current status before performing state-changing actions.\n\n### 422 -- unprocessable\n\n**Message**: Varies. Example: \"The project has no published interview guide.\"\n\n**Cause**: The request is syntactically valid but cannot be processed due to the current state of the system.\n\n**Fix**:\n- Read the error message carefully -- it usually explains exactly what needs to change.\n- Common causes include unpublished guides, disabled projects, or missing configuration.\n\n---\n\n## Rate Limiting Errors\n\n### 429 -- rate_limited\n\n**Message**: \"Rate limit exceeded. Please retry after the indicated time.\"\n\n**Cause**: You have made too many requests within the current rate limit window.\n\n**Fix**:\n- Check the `Retry-After` header for how many seconds to wait.\n- Implement exponential backoff with jitter in your retry logic.\n- Monitor `X-RateLimit-Remaining` headers to avoid hitting limits.\n\nSee [Rate Limits and CORS](/docs/rate-limits-and-cors) for implementation details.\n\n---\n\n## Server Errors (5xx)\n\nThese errors indicate a problem on Koji's side.\n\n### 500 -- internal_error\n\n**Message**: \"An unexpected error occurred. Please try again.\"\n\n**Cause**: Something went wrong on Koji's servers.\n\n**Fix**:\n- Retry the request after a short delay.\n- If the error persists, check the Koji status page for any ongoing incidents.\n- Contact support with the request ID (if provided in the response headers) and the endpoint you called.\n\n---\n\n## Embed Widget Errors\n\nIf you are using the Koji embed widget, some errors appear in the browser console rather than as API responses.\n\n### connection_failed\n\n**Cause**: The embed widget could not connect to the Koji backend at koji.so.\n\n**Fix**:\n- Check that the domain `koji.so` is accessible from your network.\n- Verify there are no Content Security Policy (CSP) headers blocking the connection.\n- Ensure the embed script is loaded from the correct source.\n\n### invalid_project\n\n**Cause**: The project ID or slug in the embed configuration does not match a valid project.\n\n**Fix**:\n- Double-check the project ID in your embed code.\n- Ensure the project is published and active.\n\n---\n\n## Getting Help\n\nIf you encounter an error not listed here or cannot resolve an issue:\n\n1. Note the **exact error code and message**.\n2. Record the **HTTP status code** if it is an API error.\n3. Check the [API Authentication](/docs/api-authentication) guide for authentication-related issues.\n4. Contact Koji support with these details for faster resolution.","category":"Troubleshooting","lastModified":"2026-04-25T19:14:08.521275+00:00","metaTitle":"Common Error Codes — Koji Docs","metaDescription":"Reference guide for Koji error codes including API, widget, and dashboard errors with fixes.","keywords":["error codes","api errors","troubleshooting","401 unauthorized","403 forbidden","429 rate limit"],"aiSummary":"Reference guide for Koji error codes. Covers authentication errors (401, 403), request errors (400, 404, 409, 422), rate limiting (429), server errors (500), and embed widget errors. Includes four API permissions: interview:start, interview:chat, interview:complete, interview:read.","aiPrerequisites":["api-authentication"],"aiLearningOutcomes":["Interpret HTTP error status codes","Debug authentication errors","Handle rate limit responses","Troubleshoot widget and dashboard errors"],"aiDifficulty":"intermediate","aiEstimatedTime":"7 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}