> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interhuman.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Error handling
> Common error formats and troubleshooting tips.
**Interhuman APIs return structured JSON error responses so you can detect, log, and recover from failures programmatically.**
If you run into issues you cannot explain, please contact us at [support@interhuman.ai](mailto:support@interhuman.ai) and include the `error_id` and `correlation_id` from the response, the endpoint you called, an approximate timestamp, and if possible a redacted example of the request. This information lets us quickly trace the failing request in our systems.
## Structured error shape
```json theme={null}
{
"error_id": "ih2005",
"correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"link": "https://docs.interhuman.ai/api-reference/error-handling#ih2005-missing-key-secret",
"message": "The `key_secret` field is absent from the request body. This field is required to authenticate your API key."
}
```
Each field has a specific purpose:
* `error_id`: A stable machine-readable error code (for example, `ih2001`). You can use this to branch your client logic.
* `correlation_id`: A unique identifier for the failing request. Log this value and include it in any support requests so we can trace the request in our systems.
* `link`: A URL that points directly to the documentation section for this specific error. You can open this link from your terminal, logs, or browser to jump to the docs for that error and see more context and remediation steps.
* `message`: A human-readable explanation you can show in logs or user-facing error messages.
## Error catalog
The catalog below lists all current error IDs (`error_id` values), grouped by category. You can search this page for a specific `error_id` (for example, `ih2001`) to jump straight to its description.
### General
#### ih1001 - Internal Server Error
This error indicates that our service encountered an unexpected condition while processing your request. This means the request was received and understood, but we were unable to complete it due to an internal issue.
In most cases, this is temporary and may be resolved by retrying the request after a short delay. We recommend implementing retry logic with exponential backoff.
If you encounter this error, it generally reflects a problem on our side rather than an issue with your request, unless otherwise indicated in the response body.
#### ih1002 - Service Temporarily Unavailable
This error indicates that our service is currently unable to process your request due to temporary conditions such as maintenance, system overload, or a dependency outage. This status is typically transient.
We recommend retrying the request after a short delay and implementing retry logic with exponential backoff. When provided, please respect the Retry-After header, which indicates how long to wait before attempting the request again.
If the issue persists beyond a reasonable period, contact support so we can investigate further.
#### ih1003 - Dependency Unavailable
A required backend dependency (such as our database) is temporarily unavailable. The request was received and authenticated, but we could not reach the dependency needed to complete it. This status is typically transient.
We recommend retrying the request after a short delay and implementing retry logic with exponential backoff.
If the issue persists beyond a reasonable period, contact support so we can investigate further.
***
### Authentication and authorization
#### ih2001 - Invalid Credentials
The provided credentials are invalid. The API key submitted in `Authorization: Bearer ` does not match an active key. For security reasons we do not reveal whether the key was unrecognized, disabled, or revoked.
##### How to fix
1. Verify your API key is correct.
2. Ensure you are not using a rotated, disabled, or revoked key.
3. If you have recently rotated your credentials, use the new value.
4. Contact support if the problem persists.
#### ih2002 - Missing Credentials
No authentication credential was found in the `Authorization` header (for HTTP requests) or the `Sec-WebSocket-Protocol` header (for WebSocket connections).
##### How to fix
1. Include your API key in the `Authorization` header as `Bearer `.
2. For WebSocket connections, pass the API key via the `Sec-WebSocket-Protocol` header.
#### ih2003 - Insufficient Scope
The API key is valid but is not provisioned with the scope required by this endpoint.
##### How to fix
* Have the key reissued or updated with the required scope.
#### ih2013 - Origin Not Allowed
The client token restricts which browser origins may use it, and this connection's `Origin` is absent or not on the token's allow-list.
##### How to fix
* Connect from an origin included in the token's `allowed_origins`.
* When minting the token, include every origin the browser will connect from in `allowed_origins` (or omit it to allow any origin).
#### ih2014 - Token Revoked
The client token was revoked by the backend that minted it, so it can no longer be used.
##### How to fix
* Mint a new client token and reconnect with it.
***
### Rate limits and quotas
#### ih3001 - Rate Limit Exceeded
You have exceeded the configured requests-per-minute limit for your account.
##### How to fix
1. Reduce the frequency of your requests.
2. Implement retry logic with exponential backoff.
3. Respect the `Retry-After` response header.
4. Contact support if you need a higher rate limit.
#### ih3002 - Concurrent Request Limit
You have exceeded the maximum number of concurrent in-flight requests allowed for your account.
##### How to fix
* Wait for one or more active requests to complete before submitting another. Consider implementing a request queue to manage concurrency.
#### ih3003 - Quota Exceeded
Your account has exhausted its analysis quota (e.g. total video-minutes for the current billing period or credit allowance).
##### How to fix
* Contact support to upgrade your plan, purchase additional credits, or wait for the quota to reset at the start of the next billing period.
#### ih3004 - Daily Quota Exceeded
Your account has exhausted its daily analysis quota.
##### How to fix
* Wait for the quota to reset (the `reset_time` is included in the response) or contact support to increase your daily limit.
#### ih3005 - Inactive Subscription
Your subscription is inactive or your billing information needs to be updated.
##### How to fix
* Contact support to reactivate your subscription or update your billing information.
#### ih3006 - Token Video Budget Exhausted
The client token has a per-token limit on the total seconds of video it may process (across upload, stream, and real-time), and that budget is now used up.
##### How to fix
* Mint a new client token, optionally with a larger `max_video_seconds` budget, and reconnect with it.
***
### Input validation
#### ih4001 - Missing Video File
No video file was included in the multipart form data, or the field name is incorrect.
##### How to fix
* Include the video file as a `multipart/form-data` field named `file`. Ensure the `Content-Type` header is set to `multipart/form-data`.
#### ih4002 - Unsupported File Type
The file extension or detected content type is not in the list of supported formats.
##### How to fix
* Re-encode or convert the video to a supported format. Supported formats include: MP4, AVI, MOV, MKV, WebM.
#### ih4003 - File Too Large
The uploaded file exceeds the maximum upload size.
##### How to fix
* Reduce the file size by compressing the video, lowering the resolution, or trimming the duration.
#### ih4004 - Video Too Long
The video duration exceeds the maximum allowed length for a single request.
##### How to fix
* Split the video into shorter segments and submit each one separately.
#### ih4005 - Invalid Parameter
A query parameter or body field has a value that is syntactically valid but outside its allowed range or fails semantic validation.
##### How to fix
* Review the parameter value mentioned in the error message and ensure it falls within the documented range.
#### ih4006 - Invalid JSON
The request body or a WebSocket control message could not be parsed as valid JSON.
##### How to fix
* Ensure the `Content-Type` header is `application/json` and the body is well-formed JSON. Validate your JSON payload with a linter before sending.
#### ih4007 - Video Too Short
The video is shorter than the minimum supported duration (3 seconds) or contains too little data to be analyzed. Recordings below this threshold cannot be analyzed.
##### How to fix
* Ensure the video is at least 3 seconds long.
***
### Content and media issues
#### ih5001 - Empty Video
The video file reports a duration of zero, or the duration cannot be determined at all. This typically indicates an empty file or a container with no media tracks.
##### How to fix
* Verify the video file plays correctly in a media player before uploading. Re-record or re-encode the file if necessary.
#### ih5002 - Corrupted Video
The video file reports a negative duration or the container structure cannot be inspected, indicating corruption or an unrecognizable format.
##### How to fix
* Re-encode the video using a standard tool (e.g. ffmpeg) with a supported codec and container format.
#### ih5003 - Unsupported Codec
The video codec or container format is not supported and cannot be decoded.
##### How to fix
* Re-encode the video using a widely supported codec and container, such as H.264 video in an MP4 container with AAC audio.
#### ih5004 - Malformed Video Segment
A video segment is structurally invalid: it is missing required container atoms and cannot be processed.
##### How to fix
* Verify the video file is complete and not truncated. Re-encode the file using a tool like ffmpeg with the `-movflags +faststart` flag.
#### ih5005 - Video Segment Too Large
A video segment exceeds the per-segment size cap enforced before analysis.
The maximum segment size is 32MB.
##### How to fix
* Reduce the video resolution or bitrate before uploading, or split the video into shorter segments.
#### ih5006 - Video Segment Too Short
A video segment is shorter than the minimum supported duration (3 seconds) or contains too little data to be analyzed.
##### How to fix
* Send chunks that each contain at least 3 seconds of media.
#### ih5007 - Content Rejected by Model
The analysis service rejected the video content. This may occur due to content policy filtering or an unsupported media payload.
##### How to fix
1. Verify the video is valid and does not violate the service's usage policies.
2. Try re-encoding the video if the issue persists.
***
### Session issues
#### ih6001 - Invalid Session Config Message
A text frame sent on `/v1/stream/analyze` did not match the documented session-config schema. The endpoint accepts inbound JSON text frames carrying caller-supplied session config (`include` and future extensions); the client may send a new config at any time and the most recent successful frame wins. The server closes the connection on a rejected frame so an invalid config cannot silently downgrade the session.
The error message describes which part of the payload failed validation (for example, an unknown field or a value outside the documented enum).
##### How to fix
1. Confirm the text frame is a JSON object matching the documented session-config schema.
2. Verify every field name and value is in the documented set.
3. Reconnect and resend the corrected config.
#### ih6002 - Message Too Large
A single binary video chunk sent over the WebSocket connection exceeds the maximum permitted message size.
The maximum message size is 32MB.
##### How to fix
1. Send smaller video chunks.
2. Reduce the chunk duration or video bitrate.
#### ih6003 - Session Idle Timeout
The connection was idle (no data received from the client) for longer than the configured session timeout.
The maximum idle time is 5 minutes.
##### How to fix
1. Send video data regularly to keep the session active.
2. If you need a longer idle period, reconnect when ready to resume.
#### ih6004 - Session Duration Exceeded
The total elapsed time for the WebSocket session has exceeded the maximum allowed session duration.
The maximum session duration is 60 minutes.
##### How to fix
1. Start a new WebSocket session.
2. If you need longer sessions, contact support to discuss your use case.
#### ih6005 - Server Going Away
The server is performing a scheduled update and has gracefully closed your WebSocket session.
##### How to fix
1. Reconnect to the WebSocket endpoint to start a new session.
2. This is a transient condition — the service will be available again shortly.
#### ih6006 - Shutdown Warning
The server is warning that it will shut down soon for a scheduled update. The connection remains open until the countdown expires, at which point the session will be closed with IH6005.
Generally, an advance notice is sent 5 minutes before shutdown. The `seconds_remaining` field in the message indicates how long until the connection closes. A final warning is sent 30 seconds before shutdown.
##### How to fix
1. Prepare to reconnect when the session is closed.
2. This is an advance notice — you can continue sending data until the connection closes.
#### ih6007 - Unreadable Video Segment
A video segment you sent could not be decoded and was skipped when measuring its duration. It may be malformed or incomplete — for example a truncated final segment produced at the end of a recording.
This notice is non-fatal: the connection stays open, the segment is still included in the session where possible, and analysis continues with the readable segments. The `segment` field identifies which segment was affected.
##### How to fix
1. Ensure each segment sent over the WebSocket is a well-formed, decodable video fragment (for MediaRecorder, that media clusters are not split or truncated across segment boundaries, especially on the final flush).
2. If the notice only appears for the last segment of a session, verify the recorder is flushed cleanly before the stream is closed.
#### ih6008 - Session Byte Limit Exceeded
The session reached the maximum cumulative upload size allowed by the client token (its `max_bytes` cap), so the connection was closed.
##### How to fix
* Mint a new client token to start a fresh session.
* When minting, set a `max_bytes` budget appropriate for the expected session length, or omit it to rely only on the duration and idle limits.
#### ih6009 - Session Closing
A binary video chunk arrived after you requested a graceful session close with the `session.close` message, so it was rejected. Once the close request is acknowledged (`session.closing`), the API accepts no new video: it finishes analyzing the video it already accepted, emits the final lifecycle messages, sends `session.ended`, and closes the connection.
This notice is non-fatal and is sent at most once per session: further chunks are dropped silently while the session drains.
##### How to fix
1. Stop sending video before (or immediately after) sending `session.close`.
2. Keep the connection open and keep reading messages until `session.ended` arrives, then treat the session as complete.