> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes

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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="INVALID_API_KEY (401)">
    Missing or invalid `Authorization` header / API key for the endpoint or company.\
    **Typical messages:** `"Missing API key"`, `"Invalid API key"`.
  </Accordion>
</AccordionGroup>

***

### Request Validation (Generic)

<AccordionGroup>
  <Accordion title="INVALID_REQUEST (400)">
    Missing request body or required parameters (varies by endpoint).\
    **Typical messages:** `"Missing request body"`, `"Missing companyId parameter"`, `"Missing clipId parameter"`.
  </Accordion>
</AccordionGroup>

***

### URL / Time Validation (Clip Generation)

<AccordionGroup>
  <Accordion title="INVALID_URL (400)">
    Missing or invalid URL parameter.\
    **Typical messages:** `"Missing URL parameter"`.
  </Accordion>

  <Accordion title="INVALID_YOUTUBE_URL (400)">
    URL appears to be YouTube but fails format validation.\
    **Typical messages:** `"Invalid YouTube URL format"`.
  </Accordion>

  <Accordion title="INVALID_TIME (400)">
    `minimumTime` / `maximumTime` out of allowed range.
  </Accordion>

  <Accordion title="VIDEO_TOO_SHORT (400)">
    Video is shorter than the requested minimum clip length.
  </Accordion>

  <Accordion title="VIDEO_LENGTH_ERROR (400)">
    Couldn’t fetch or compute video length.\
    **Typical messages:** contains provider-specific detail about the failure.
  </Accordion>

  <Accordion title="INSUFFICIENT_HOURS (403)">
    Team/company doesn’t have enough quota hours to process the request.\
    **Typical messages:** includes quota detail in the message.
  </Accordion>
</AccordionGroup>

***

### Task / Workflow Lookup + Authorization

<AccordionGroup>
  <Accordion title="TASK_NOT_FOUND (404)">
    Task ID doesn’t exist.
  </Accordion>

  <Accordion title="UNAUTHORIZED_ACCESS (403)">
    Task exists but belongs to a different team/company.
  </Accordion>

  <Accordion title="WORKFLOW_TRIGGER_NOT_FOUND (404)">
    Workflow trigger ID not found.
  </Accordion>
</AccordionGroup>

***

### Workflow Validation / Quotas

<AccordionGroup>
  <Accordion title="WORKFLOW_TRIGGER_LIMIT_REACHED (403)">
    Company hit workflow trigger quota limit.
  </Accordion>

  <Accordion title="VALIDATION_ERROR (varies)">
    Workflow/company validation failed (validator returns the details).\
    **Typical messages:** depends on the specific validation failure.
  </Accordion>

  <Accordion title="WORKFLOW_NOT_FOUND (404)">
    Workflow document not found for the company.
  </Accordion>
</AccordionGroup>

***

### Render Endpoint

<AccordionGroup>
  <Accordion title="MISSING_COMPANY_ID (400)">
    `/render` missing `companyId`.
  </Accordion>

  <Accordion title="MISSING_CLIP_ID (400)">
    `/render` missing `clipId`.
  </Accordion>

  <Accordion title="EXCEEDED_RATE_LIMIT (429)">
    Too many in-flight render jobs for the company.\
    **Typical messages:** `"Render job limit reached..."`.
  </Accordion>

  <Accordion title="CLIP_NOT_FOUND (404)">
    Clip doc not found under `companies/{companyId}/clips/{clipId}`.
  </Accordion>

  <Accordion title="RENDER_FAILED (500)">
    Rendering returned no URL.\
    **Typical messages:** `"Failed to render video..."`.
  </Accordion>
</AccordionGroup>

***

### Analytics Endpoints

<AccordionGroup>
  <Accordion title="MISSING_POST_ID (400)">
    `/post-analytics` missing `postId`.
  </Accordion>

  <Accordion title="POST_NOT_FOUND (404)">
    Post doc not found under `companies/{companyId}/posts/{postId}`.
  </Accordion>

  <Accordion title="INVALID_QUERY (400)">
    Invalid query parameter combination on `/posts` or `/post-analytics` —
    e.g. an unsupported `sortBy` value, a non-integer `limit`, or
    `startDate`/`endDate` combined with a metric sort.
  </Accordion>

  <Accordion title="INVALID_CURSOR (400)">
    `/posts` received a `cursor` that doesn't reference a known post. Cursors
    come from the previous page's response and shouldn't be constructed by hand.
  </Accordion>
</AccordionGroup>

***

### Playback Helper

<AccordionGroup>
  <Accordion title="REPLAY_URL_NOT_FOUND (404)">
    Playback API returned 200 but no `replayHLSURL`.
  </Accordion>

  <Accordion title="PLAYBACK_API_ERROR (varies)">
    Playback API returned a non-200 response.\
    **Typical messages:** `"Failed to fetch playback data"`.
  </Accordion>

  <Accordion title="INTERNAL_ERROR (500)">
    Exception while calling the Playback API.\
    **Typical messages:** `"Internal server error"`.
  </Accordion>
</AccordionGroup>

***

### Subtitles Endpoints

<AccordionGroup>
  <Accordion title="SUBTITLE_CONFIG_NOT_FOUND (422)">
    Clip exists but has no `subtitleConfig`.
  </Accordion>

  <Accordion title="INVALID_STYLE_ID_TYPE (400)">
    `subtitleConfig.styleId` exists but isn’t a string.
  </Accordion>

  <Accordion title="INVALID_SUBTITLE_CONFIG (400)">
    `subtitleConfig` in the request is not a JSON object (dict).
  </Accordion>

  <Accordion title="CLIP_NOT_FOUND (404)">
    Clip not found when fetching or updating subtitles.
  </Accordion>

  <Accordion title="SERVER_ERROR (500)">
    Failure retrieving/updating subtitle configuration.\
    **Typical messages:** `"Failed to retrieve/update subtitle configuration: ..."`.
  </Accordion>
</AccordionGroup>

***

### Server / Processing Failures

<AccordionGroup>
  <Accordion title="SERVER_ERROR (500)">
    Unhandled exception in an endpoint.\
    **Typical messages:** often the exception string.
  </Accordion>

  <Accordion title="TRIGGER_ERROR (500)">
    Exception while processing a workflow trigger request.\
    **Typical messages:** `"Failed to process workflow trigger: ..."`.
  </Accordion>

  <Accordion title="KEY_GENERATION_ERROR (500)">
    Failure generating an API key.\
    **Typical messages:** `"Failed to generate API key: ..."`.
  </Accordion>
</AccordionGroup>

***

## Recommended Client Handling

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