Skip to main content
Interhuman APIs return structured JSON error responses so you can detect, log, and recover from failures programmatically. During a short transition period, error responses include both a legacy shape (for backwards compatibility) and a new structured shape:
  • Legacy fields (to be removed): { "detail": string, "status_code": number, "extra": object }
  • New structured fields (canonical going forward): { "error_id": string, "correlation_id": string, "link": string, "message": string }
Until March 20, 2026, responses will continue to include the legacy fields. After March 20, 2026, only the structured fields will be returned. New integrations should use only the structured error format. 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.

​
Error response formats

​
Current behavior (transition period)

During the transition period, a typical error response looks like this: 
{
  "detail": "The key_secret field is absent from the request body. This field is required to authenticate your API key."
  "status_code": 400,
  "extra": {},
  "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."
}
  • Existing integrations that rely on detail, status_code, or extra should migrate to use error_id, correlation_id, link, and message before March 20, 2026.
  • New integrations should ignore the legacy fields and rely only on the structured ones.

​
Structured error shape

After the transition period, error responses will only contain the structured fields: 
{
  "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.

​
Authentication and authorization

​
ih2001 - Invalid Scope

One or more values in the scopes list are not recognized. This is validated before the request reaches the server — the response is returned immediately.
How to fix
  • Check that every value in your scopes array is spelled exactly as shown in the valid-scopes table. Scope values are case-sensitive.
Valid scopes
ScopeGrants access to
interhumanai.uploadPOST /v0/upload/analyze — analyze a pre-recorded video file
interhumanai.streamGET /v0/stream/analyze — analyze a live video stream over WebSocket
You may request one or both scopes in a single token.

​
ih2002 - Empty Scopes List

The scopes field is present in the request body but the list is empty. At least one scope must be requested.
How to fix
  • Add one or more valid scope values to the scopes array. Valid scopes are interhumanai.upload and interhumanai.stream.

​
ih2003 - Missing Scopes

The scopes field is absent from the request body. This field is required.
How to fix
  • Include a scopes field in the JSON body with an array of one or more valid scope values.

​
ih2004 - Missing Key ID

The key_id field is absent from the request body. This field is required to identify your API key.
How to fix
  • Include a key_id field in the JSON body. Your key ID was provided when your account was created.

​
ih2005 - Missing Key Secret

The key_secret field is absent from the request body. This field is required to authenticate your API key.
How to fix
  • Include a key_secret field in the JSON body. If you have lost your key secret, contact support to rotate your credentials.

​
ih2006 - Invalid Credentials

The provided key_id does not exist or the key_secret does not match. For security reasons we do not reveal which value is incorrect.
How to fix
  1. Verify your key_id and key_secret are correct.
  2. Ensure you are not using a rotated or revoked key.
  3. If you have recently rotated your credentials, use the new values.
  4. Contact support if the problem persists.

​
ih2007 - Unauthorized Scope

The API key is valid but is not authorized for one or more of the requested scopes. Each API key is provisioned with specific scope permissions.
How to fix
  1. Review the scopes assigned to your API key.
  2. Request only the scopes your key is authorized for.
  3. Contact support if you need additional scope access.

​
ih2008 - Missing Token

No Bearer token was found in the Authorization header (for HTTP requests) or the sec-websocket-protocol header (for WebSocket connections).
How to fix
  1. Obtain a token by calling POST /v0/auth with valid credentials.
  2. Include the token in the Authorization header as Bearer <token>.
  3. For WebSocket connections, pass the token via the sec-websocket-protocol header.

​
ih2009 - Token Expired

The JWT token’s expiry claim has passed. Tokens have a limited lifetime for security.
How to fix
  • Request a new token by calling POST /v0/auth with your credentials. Consider refreshing your token proactively before it expires.

​
ih2010 - Invalid Token

The JWT token signature is invalid or the payload is malformed and cannot be decoded.
How to fix
  1. Ensure you are using a token obtained from POST /v0/auth.
  2. Verify the token has not been modified or truncated.
  3. Request a fresh token if the issue persists.

​
ih2011 - Insufficient Scope

The JWT token is valid but does not contain the scope required by this specific endpoint.
How to fix
  • Request a new token that includes the required scope. Each endpoint documents which scope it requires.

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

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

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

A video segment is below the minimum size threshold and contains too little data to be analyzed. The minimum segment size is 10KB.
How to fix
  • Ensure the video is at least a few seconds long and contains actual video content.

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

​
Realtime and session issues

​
ih6001 - Invalid Message Format

A text or binary message sent by the client does not match the expected protocol schema.
How to fix
  1. Review the WebSocket API documentation.
  2. Ensure messages conform to the expected format.

​
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 20MB.
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.