Skip to main content

​
Overview

Overlap API endpoints return structured error responses when a request fails. This page lists common error codes you may receive across all integrations, what they mean, and the typical HTTP status codes/messages.

​
Error response shape

{
  "errorCode": "INVALID_REQUEST",
  "message": "Missing request body"
}
Notes
  • errorCode is the stable, programmatic identifier to key off of.
  • message is human-readable and may change slightly over time.
  • HTTP status codes generally align with the category (4xx client errors, 5xx server errors).

​
Error Code Reference

​
Auth / API Key

Missing or invalid Authorization header / API key for the endpoint or company.
Typical messages: "Missing API key", "Invalid API key".

​
Request Validation (Generic)

Missing request body or required parameters (varies by endpoint).
Typical messages: "Missing request body", "Missing companyId parameter", "Missing clipId parameter".

​
URL / Time Validation (Clip Generation)

Missing or invalid URL parameter.
Typical messages: "Missing URL parameter".
URL appears to be YouTube but fails format validation.
Typical messages: "Invalid YouTube URL format".
minimumTime / maximumTime out of allowed range.
Video is shorter than the requested minimum clip length.
Couldn’t fetch or compute video length.
Typical messages: contains provider-specific detail about the failure.
Team/company doesn’t have enough quota hours to process the request.
Typical messages: includes quota detail in the message.

​
Task / Workflow Lookup + Authorization

Task ID doesn’t exist.
Task exists but belongs to a different team/company.
Workflow trigger ID not found.

​
Workflow Validation / Quotas

Company hit workflow trigger quota limit.
Workflow/company validation failed (validator returns the details).
Typical messages: depends on the specific validation failure.
Workflow document not found for the company.

​
Render Endpoint

/render missing companyId.
/render missing clipId.
Too many in-flight render jobs for the company.
Typical messages: "Render job limit reached...".
Clip doc not found under companies/{companyId}/clips/{clipId}.
Rendering returned no URL.
Typical messages: "Failed to render video...".

​
Playback Helper

Playback API returned 200 but no replayHLSURL.
Playback API returned a non-200 response.
Typical messages: "Failed to fetch playback data".
Exception while calling the Playback API.
Typical messages: "Internal server error".

​
Subtitles Endpoints

Clip exists but has no subtitleConfig.
subtitleConfig.styleId exists but isn’t a string.
subtitleConfig in the request is not a JSON object (dict).
Clip not found when fetching or updating subtitles.
Failure retrieving/updating subtitle configuration.
Typical messages: "Failed to retrieve/update subtitle configuration: ...".

​
Server / Processing Failures

Unhandled exception in an endpoint.
Typical messages: often the exception string.
Exception while processing a workflow trigger request.
Typical messages: "Failed to process workflow trigger: ...".
Failure generating an API key.
Typical messages: "Failed to generate API key: ...".

​
Retryable (usually)

  • SERVER_ERROR, TRIGGER_ERROR, INTERNAL_ERROR
  • PLAYBACK_API_ERROR when the HTTP status is 5xx
Use exponential backoff and cap retries.

​
Fix request and retry

  • INVALID_REQUEST, INVALID_URL, INVALID_YOUTUBE_URL, INVALID_TIME, INVALID_SUBTITLE_CONFIG

​
Auth / permissions

  • INVALID_API_KEY, UNAUTHORIZED_ACCESS

​
Quotas / throttling

  • INSUFFICIENT_HOURS, WORKFLOW_TRIGGER_LIMIT_REACHED, EXCEEDED_RATE_LIMIT
Avoid retries until quota resets or concurrency drops.