Common Error Codes

When 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.

---

How Errors Are Structured

Koji returns errors as JSON objects with a consistent structure:

{
  "error": "error_code",
  "message": "A human-readable description of what went wrong."
}

The error field is a machine-readable code you can use in your application logic. The message field provides a plain-language explanation.

For API errors, the HTTP status code also indicates the category of the problem.

---

Authentication Errors (4xx)

These errors relate to API keys, session tokens, and account permissions.

401 — unauthorized

Message: "The provided API key is invalid or has been revoked."

Cause: Your API key is missing from the request, is malformed, or has been revoked.

Fix:

• Check that the Authorization header is present and formatted as Bearer your_api_key.
• Verify the key has not been revoked in Settings > Integrations.
• Make sure you copied the full key without extra spaces.

See API Authentication for details.

401 — invalid_session_token

Message: "The session token is invalid or expired."

Cause: The X-Session-Token header contains an invalid or expired token.

Fix:

• Use the session token exactly as returned by the start endpoint.
• Session tokens are tied to a specific interview and expire after the interview is completed or timed out.
• If the token has expired, you need to start a new interview.

403 — forbidden

Message: "Your API key does not have the required permission for this action."

Cause: The API key exists and is valid, but it does not have the permission needed for the endpoint you are calling.

Fix:

• Check which permissions your key has in Settings > Integrations.
• Add the missing permission (e.g., interview:start, interview:read, or interview:complete).

403 — feature_not_available

Message: "This feature is not available on your current plan."

Cause: You are trying to use a feature that requires a higher plan tier. For example, API access requires the Scale plan.

Fix:

• Check your current plan in Account Settings > Billing.
• Upgrade to the required plan tier. See plan comparison guide.

---

Request Errors (4xx)

These errors indicate problems with the request itself.

400 — invalid_request

Message: Varies. Examples: "The field project_id is required." or "Invalid JSON in request body."

Cause: The request body is missing required fields, contains invalid values, or has malformed JSON.

Fix:

• Check the endpoint documentation for required fields.
• Validate your JSON syntax before sending.
• Ensure all field types match what the API expects (strings, UUIDs, etc.).

404 — not_found

Message: "The requested resource was not found."

Cause: The interview, project, or guide ID in your request does not match any existing resource.

Fix:

• Verify the ID is correct. UUIDs are case-sensitive.
• Confirm the resource exists in the Koji dashboard.
• Check that the resource belongs to the project your API key is scoped to.

409 — conflict

Message: Varies. Example: "This interview has already been completed."

Cause: The action you are trying to perform conflicts with the current state of the resource.

Fix:

• For "already completed" errors, this is usually benign — the interview was completed previously.
• Check the resource's current status before performing state-changing actions.

422 — unprocessable

Message: Varies. Example: "The project has no published interview guide."

Cause: The request is syntactically valid but cannot be processed due to the current state of the system.

Fix:

• Read the error message carefully — it usually explains exactly what needs to change.
• Common causes include unpublished guides, disabled projects, or missing configuration.

---

Rate Limiting Errors

429 — rate_limited

Message: "Rate limit exceeded. Please retry after the indicated time."

Cause: You have made too many requests within the current rate limit window.

Fix:

• Check the Retry-After header for how many seconds to wait.
• Implement exponential backoff with jitter in your retry logic.
• Monitor X-RateLimit-Remaining headers to avoid hitting limits.

See Rate Limits and CORS for implementation details.

---

Server Errors (5xx)

These errors indicate a problem on Koji's side.

500 — internal_error

Message: "An unexpected error occurred. Please try again."

Cause: Something went wrong on Koji's servers.

Fix:

• Retry the request after a short delay.
• If the error persists, check the Koji status page for any ongoing incidents.
• Contact support if the issue continues.

502 — bad_gateway

Message: "The service is temporarily unavailable."

Cause: A temporary infrastructure issue is preventing the request from being processed.

Fix:

• Wait a few seconds and retry.
• These errors are almost always transient and resolve on their own.

503 — service_unavailable

Message: "The service is currently undergoing maintenance."

Cause: Koji is performing scheduled or emergency maintenance.

Fix:

• Wait for maintenance to complete.
• Check the Koji status page for estimated resolution times.

---

Widget Errors

These errors appear in the embed widget and are communicated via the PostMessage API.

widget_load_failed

Message: "The interview widget could not be loaded."

Cause: The project ID in the embed URL is invalid, the project is archived, or there is a network issue.

Fix:

• Verify the project ID in the iframe src URL.
• Confirm the project exists and is active.
• Check that the host page can reach app.getkoji.com.

microphone_denied

Message: "Microphone access was denied by the user or browser."

Cause: The browser does not have permission to access the microphone.

Fix:

• Ensure the iframe has the allow="microphone" attribute.
• Check browser-level microphone permissions.
• See Voice Interview Not Working for step-by-step instructions.

session_expired

Message: "The interview session has expired."

Cause: The interview session timed out due to inactivity.

Fix:

• Start a new interview. Expired sessions cannot be resumed.
• If this is happening frequently, consider adjusting interview length or adding engagement prompts.

---

Debugging Tips

For API Integrations

• Log full responses. Capture both the HTTP status code and the response body for every API call. This makes debugging much faster.
• Check headers. Rate limit headers, session token requirements, and CORS headers often provide clues before you even look at the response body.
• Use the correct environment. Make sure you are pointing at the production API, not a stale or incorrect URL.

For Embed Widget

• Open browser developer tools. The Console tab shows widget errors and PostMessage events.
• Check the Network tab. Failed requests to app.getkoji.com indicate connectivity or configuration issues.
• Test in incognito. Browser extensions can interfere with the widget. Incognito mode disables most extensions.

For Dashboard Issues

• Hard refresh. Ctrl+Shift+R (Cmd+Shift+R on Mac) clears cached files.
• Try a different browser. Isolates the issue to browser-specific problems.
• Check your internet connection. Flaky connections can cause partial page loads.

---

Next Steps

• Set up authentication correctly
• Understand rate limits