Error Handling

All API errors return a consistent JSON envelope.

Error format

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable description"
  }
}

Error codes

Code	HTTP Status	Description
authentication_error	401	Invalid or missing API key
validation_error	400	Invalid request parameters
not_found	404	Resource does not exist
rate_limit_exceeded	429	Too many requests
limit_exceeded	403	API requires Business+, or video minutes exhausted
insufficient_scope	403	OAuth token wasn't granted the scope this endpoint needs
insufficient_role	403	The workspace role behind the token can't perform this action
folder_read_only	403	The item is in a read-only project — readable, but not yours to change
conflict	409	The request conflicts with current state
locked	423	The video's content is locked and can't be changed
internal_error	500	Server error

Handling errors

Authentication errors (401)

Check that your API key is valid, not revoked, and included in the Authorization header with the Bearer prefix.

Validation errors (400)

The message field describes which parameter is invalid. Fix the request body or query parameters and retry.

{
  "error": {
    "code": "validation_error",
    "message": "Must be a video content type"
  }
}

Not found (404)

The requested resource doesn't exist or belongs to a different workspace.

Rate limit exceeded (429)

You've exceeded the 60 requests-per-minute limit. Wait for the window to reset. See Rate Limiting for details.

Limit exceeded (403)

Returned when you're out of video minutes - you've used your monthly allowance. It resets at the start of your next billing cycle. Every Vidocu plan, including Free, has API access; only the allowance differs. See Plans & Limits.

{
  "error": {
    "code": "limit_exceeded",
    "message": "Video minutes quota exceeded. Used 60 of 60 minutes this period. Quota resets at the start of your next billing cycle."
  }
}

Insufficient role (403)

Only for OAuth tokens. Scopes describe what an integration asked for; the workspace role behind the token describes what that person may do, and both must allow the action. A token minted by a viewer can hold videos:write and still be refused.

{
  "error": {
    "code": "insufficient_role",
    "message": "Your workspace role \"viewer\" is not allowed to modify videos."
  }
}

API keys are not affected - a key authenticates as a workspace, not a user, and carries full workspace permissions.

Locked (423)

The video's content is locked. Locking freezes a package so it stays stable through an approval cycle: analysis, voiceover, translation and help-article regeneration are all refused until it's unlocked in the Vidocu app.

{
  "error": {
    "code": "locked",
    "message": "This video is locked by Dana Levi on 2026-08-01T09:14:00.000Z and can't be changed. Unlock it before you re-analyze it."
  }
}

Two things that still work while locked:

• Exporting. Rendering an artifact from frozen content is the point of a locked package.
• Moving it between projects. Filing isn't content.

GET /v1/videos/:id returns locked and lock, so you can check before you call. Deleting a project with ?cascade=true is refused outright if it contains any locked video.

Blocked URLs

Any URL you hand the API is fetched by our servers, so URLs pointing at internal or private addresses are refused:

{
  "error": {
    "code": "validation_error",
    "message": "videoUrl must point at a public host - internal and private addresses are not allowed"
  }
}

This covers localhost, loopback, link-local (169.254.x, cloud instance metadata), and the RFC 1918 private ranges, on video uploads, /process, tool inputs and webhook URLs.

Internal errors (500)

A server-side issue occurred. These are rare — retry after a short delay. If persistent, contact support.