Error handling - Interhuman AI Documentation

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

{
  "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.

ih1004 - Job Interrupted

An asynchronous analysis job (POST /v2/upload/analyze) was accepted and then interrupted before it completed — the worker processing it restarted. Jobs are not resumed after a restart, so the job is reported as failed with this code the next time its status is read.

How to fix

Submit the file again as a new job.
If this recurs for the same file, contact support with the correlation_id of the failed job.

Authentication and authorization

ih2001 - Invalid Credentials

The provided credentials are invalid. The API key submitted in Authorization: Bearer <api_key>, or in the api_key field of POST /v1/client_tokens, does not match an active key. For security reasons we do not reveal whether the key was unrecognized, disabled, or revoked.

How to fix

Verify your API key is correct.
Ensure you are not using a rotated, disabled, or revoked key.
If you have recently rotated your credentials, use the new value.
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

Send your API key, or a client token minted by POST /v1/client_tokens, in the Authorization header as Bearer <credential>.
WebSocket connections accept the same Authorization header, or — for clients that cannot set it, such as browsers — the Sec-WebSocket-Protocol: access_token, <credential> subprotocol pair. Both schemes carry either credential.

ih2003 - Insufficient Scope

The API key or client token is valid but does not carry the scope this endpoint requires. The message names it: interhumanai.upload for POST /v1/upload/analyze, POST /v2/upload/analyze and GET /v2/upload/jobs/{job_id}, and interhumanai.stream for /v1/stream/analyze and /v2/stream/analyze.

How to fix

With an API key: have the key reissued or updated with the required scope.
With a client token: mint a new token whose scopes include the required scope. The API key that mints it must hold that scope too.

ih2009 - Unauthorized Scope

POST /v1/client_tokens asked for a scope the API key does not hold. A client token can carry only scopes its key holds, and the message names the ones refused.

How to fix

Request only scopes the key holds, or have the key updated with the missing scope before minting.

ih2010 - Token Expired

The client token has expired. Client tokens are short-lived by design; expires_in on the mint response says how long a token lasts.

How to fix

Mint a new client token and retry with it.
Server-side callers can send the API key instead.

ih2011 - Invalid Token

The credential in Authorization: Bearer <credential> (or the access_token subprotocol pair) is not an API key and not a valid client token. Either the token was truncated or altered, it was issued by another environment, or the API key that minted it is no longer active (disabled, revoked or deleted, as after a key rotation).

How to fix

Send the token exactly as it was issued.
After rotating or disabling a key, mint new tokens with an active key.
If you meant to send an API key, check that it starts with ih_live_ or ih_test_.

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

Reduce the frequency of your requests.
Implement retry logic with exponential backoff.
Respect the Retry-After response header.
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 media-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 Media Budget Exhausted

The client token has a per-token limit on the total seconds of media it may process (across upload and stream), 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 Media File

No media file was included in the multipart form data, or the field name is incorrect.

How to fix

Include the video or audio 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’s detected container format is not in the list of supported formats. The error message lists the accepted formats, which on POST /v2/upload/analyze depend on the model you named.

How to fix

Convert the file to a supported format. For inter-2 and POST /v1/upload/analyze, use a video: MP4, MOV, AVI, MKV, WebM or MPEG-TS. For inter-2-audio, use an audio file (WAV, FLAC, MP3, M4A or OGG), or a WebM or MP4 that carries an audio track.

ih4003 - File Too Large

The uploaded file exceeds the maximum upload size.

How to fix

Reduce the file size by compressing the media, lowering the video resolution or audio bitrate, or trimming the duration.

ih4004 - Recording Too Long

The media duration exceeds the maximum allowed length for a single request.

How to fix

Split the recording into shorter files 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 - Recording Too Short

The recording 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 recording is at least 3 seconds long.

ih4021 - Job Not Found

The job_id in GET /v2/upload/jobs/{job_id} does not name a job this account created, or the job has expired. Job records are kept for a limited time after they are created (the expires_at field of the job envelope says when); after that the id is no longer known.

How to fix

Check that the id was copied from the job_id of the submit response and that the request uses the same account’s credential.
Read the status before expires_at; if the job has expired, submit the file again.

Content and media issues

ih5001 - Empty Media

There is no media for the analysis to read. On an upload, the file reports a duration of zero or no determinable duration at all, which typically means an empty file or a container with no media tracks (with model=inter-2-audio, a file with no audio track is refused with ih5008 instead). On POST /v2/upload/analyze with model=inter-2, the file may instead carry no video stream, for example an MP4 or M4A that carries only audio. On a stream session, the media lacks the track the session’s model reads: a video track for inter-2 and the v1 stream, or an audio track for inter-2-audio. The session stays open and reports this once, then analyzes nothing further until that track arrives.

How to fix

On an upload, verify the file plays correctly in a media player before uploading: for inter-2 it must show a picture. To analyze a recording with no picture, submit it with model=inter-2-audio. Re-record or re-encode the file if necessary.
On an inter-2 or v1 stream, check that the recording was started from a source that includes video — for example a getUserMedia call whose constraints request video, and a camera whose permission was granted. To analyze a microphone alone, connect to WS /v2/stream/analyze with model=inter-2-audio.
On an inter-2-audio stream, check that the recording includes audio — for example a getUserMedia call whose constraints request audio, and a microphone whose permission was granted.
Restarting the recorder with the missing track resumes analysis.

ih5002 - Corrupted Media

The file reports a negative duration or the container structure cannot be inspected, indicating corruption or an unrecognizable format.

How to fix

Re-encode the file using a standard tool (e.g. ffmpeg) with a supported codec and container format.

ih5003 - Unsupported Codec

The codec or container format is not supported and cannot be decoded.

How to fix

Re-encode the file using a widely supported codec and container, such as H.264 video in an MP4 container with AAC audio.

ih5004 - Malformed Media Segment

A media segment is structurally invalid or truncated, so the analysis service could not process it.

How to fix

Verify the file is complete and not truncated.
Re-encode the file with a tool like ffmpeg. For an MP4, add the -movflags +faststart flag.

ih5005 - Media Segment Too Large

A media segment exceeds the per-segment size cap enforced before analysis. The maximum segment size is 32MB.

How to fix

Reduce the bitrate (and, for video, the resolution) before uploading, or split the recording into shorter segments.

ih5006 - Media Segment Too Short

A media 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 content. This may occur due to content policy filtering or an unsupported media payload.

How to fix

Verify the file is valid and does not violate the service’s usage policies.
Try re-encoding the file if the issue persists.

ih5008 - No Audio Stream

The submitted file carries no audio stream, but the requested model requires audio, so there is nothing for it to analyze. A silent video with no audio track, or a container whose audio track could not be identified, produces this error.

How to fix

Submit a file that carries an audio track: for inter-2, a video with sound; for inter-2-audio, an audio file or a video with sound. Check with a media tool (for example ffprobe) that the file reports an audio stream.

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

Confirm the text frame is a JSON object matching the documented session-config schema.
Verify every field name and value is in the documented set.
Reconnect and resend the corrected config.

ih6002 - Message Too Large

A single binary media chunk sent over the WebSocket connection exceeds the maximum permitted message size. The maximum message size is 32MB.

How to fix

Send smaller media chunks.
Reduce the chunk duration or 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

Send media data regularly to keep the session active.
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

Start a new WebSocket session.
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

Reconnect to the WebSocket endpoint to start a new session.
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

Prepare to reconnect when the session is closed.
This is an advance notice — you can continue sending data until the connection closes.

ih6007 - Unreadable Media Segment

A media 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

Ensure each segment sent over the WebSocket is a well-formed, decodable media fragment (for MediaRecorder, that media clusters are not split or truncated across segment boundaries, especially on the final flush).
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 media 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 media: it finishes analyzing the media 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

Stop sending media before (or immediately after) sending session.close.
Keep the connection open and keep reading messages until session.ended arrives, then treat the session as complete.

ih6010 - Stream Not Advancing

The media you sent could not be interpreted at all: no initialization segment ever arrived and not one chunk completed a decodable media unit (a WebM cluster or an MP4 fragment), so no window could be analyzed. The API holds such incomplete bytes so they can be joined to the chunk that completes them; once that hold exceeds its limit with no header received and nothing decoded, there is no media unit in progress to wait for and the session is closed. This normally means the initialization segment the media depends on was never sent, or the sending client is emitting a byte stream that was cut mid-fragment and never rejoined. A session that has sent its header, or decoded anything at all, is not closed for this — a single long media unit is held and joined normally.

How to fix

Send chunks that each end on a media-unit boundary — for MediaRecorder, use its own dataavailable blobs rather than re-splitting them at arbitrary byte offsets.
Send the initialization segment (the WebM header, or the MP4 ftyp/moov boxes) before the media fragments that depend on it.
Reconnect to start a fresh session once the sending client is fixed.

​Structured error shape

​Error catalog

​General

​ih1001 - Internal Server Error

​ih1002 - Service Temporarily Unavailable

​ih1003 - Dependency Unavailable

​ih1004 - Job Interrupted

How to fix

​Authentication and authorization

​ih2001 - Invalid Credentials

How to fix

​ih2002 - Missing Credentials

How to fix

​ih2003 - Insufficient Scope

How to fix

​ih2009 - Unauthorized Scope

How to fix

​ih2010 - Token Expired

How to fix

​ih2011 - Invalid Token

How to fix

​ih2013 - Origin Not Allowed

How to fix

​ih2014 - Token Revoked

How to fix

​Rate limits and quotas

​ih3001 - Rate Limit Exceeded

How to fix

​ih3002 - Concurrent Request Limit

How to fix

​ih3003 - Quota Exceeded

How to fix

​ih3004 - Daily Quota Exceeded

How to fix

​ih3005 - Inactive Subscription

How to fix

​ih3006 - Token Media Budget Exhausted

How to fix

​Input validation

​ih4001 - Missing Media File

How to fix

​ih4002 - Unsupported File Type

How to fix

​ih4003 - File Too Large

How to fix

​ih4004 - Recording Too Long

How to fix

​ih4005 - Invalid Parameter

How to fix

​ih4006 - Invalid JSON

How to fix

​ih4007 - Recording Too Short

How to fix

​ih4021 - Job Not Found

How to fix

​Content and media issues

​ih5001 - Empty Media

How to fix

​ih5002 - Corrupted Media

How to fix

​ih5003 - Unsupported Codec

How to fix

​ih5004 - Malformed Media Segment

How to fix

​ih5005 - Media Segment Too Large

How to fix

​ih5006 - Media Segment Too Short

How to fix

​ih5007 - Content Rejected by Model

How to fix

​ih5008 - No Audio Stream

How to fix

​Session issues

​ih6001 - Invalid Session Config Message

How to fix

​ih6002 - Message Too Large

How to fix

​ih6003 - Session Idle Timeout

How to fix

​ih6004 - Session Duration Exceeded

Structured error shape

Error catalog

General

ih1001 - Internal Server Error

ih1002 - Service Temporarily Unavailable

ih1003 - Dependency Unavailable

ih1004 - Job Interrupted

Authentication and authorization

ih2001 - Invalid Credentials

ih2002 - Missing Credentials

ih2003 - Insufficient Scope

ih2009 - Unauthorized Scope

ih2010 - Token Expired

ih2011 - Invalid Token

ih2013 - Origin Not Allowed

ih2014 - Token Revoked

Rate limits and quotas

ih3001 - Rate Limit Exceeded

ih3002 - Concurrent Request Limit

ih3003 - Quota Exceeded

ih3004 - Daily Quota Exceeded

ih3005 - Inactive Subscription

ih3006 - Token Media Budget Exhausted

Input validation

ih4001 - Missing Media File

ih4002 - Unsupported File Type

ih4003 - File Too Large

ih4004 - Recording Too Long

ih4005 - Invalid Parameter

ih4006 - Invalid JSON

ih4007 - Recording Too Short

ih4021 - Job Not Found

Content and media issues

ih5001 - Empty Media

ih5002 - Corrupted Media

ih5003 - Unsupported Codec

ih5004 - Malformed Media Segment

ih5005 - Media Segment Too Large

ih5006 - Media Segment Too Short

ih5007 - Content Rejected by Model

ih5008 - No Audio Stream

Session issues

ih6001 - Invalid Session Config Message

ih6002 - Message Too Large

ih6003 - Session Idle Timeout

ih6004 - Session Duration Exceeded

ih6005 - Server Going Away

ih6006 - Shutdown Warning

ih6007 - Unreadable Media Segment

ih6008 - Session Byte Limit Exceeded

ih6009 - Session Closing

ih6010 - Stream Not Advancing