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 Dashboard > Profile > API Keys.
• 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 Dashboard > Profile > API Keys.
• Add the missing permission. The four available permissions are: interview:start, interview:chat, interview:complete, and interview:read.

403 -- feature_not_available

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

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.

Fix:

• If you see this error, try refreshing the page or logging out and back in.
• Check your account status in Account Settings > Billing.
• If the issue persists, contact support -- this error should not appear for active accounts on current plans.
• See plan comparison guide for plan details.

---

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 with the request ID (if provided in the response headers) and the endpoint you called.

---

Embed Widget Errors

If you are using the Koji embed widget, some errors appear in the browser console rather than as API responses.

connection_failed

Cause: The embed widget could not connect to the Koji backend at koji.so.

Fix:

• Check that the domain koji.so is accessible from your network.
• Verify there are no Content Security Policy (CSP) headers blocking the connection.
• Ensure the embed script is loaded from the correct source.

invalid_project

Cause: The project ID or slug in the embed configuration does not match a valid project.

Fix:

• Double-check the project ID in your embed code.
• Ensure the project is published and active.

---

Getting Help

If you encounter an error not listed here or cannot resolve an issue:

1. Note the exact error code and message.
2. Record the HTTP status code if it is an API error.
3. Check the API Authentication guide for authentication-related issues.
4. Contact Koji support with these details for faster resolution.