Error Codes — VideoConduit Docs

Error Response Format

All errors return JSON with a consistent structure:

{
  "detail": "Human-readable error message",
  "code": "machine_readable_code"
}

Some errors include additional fields. For example, credit errors include required and available fields, and rate limit errors include retry_after.

HTTP Status Codes

Status	Code	Description
400	bad_request	Invalid request parameters. Check the `detail` field for specifics.
401	unauthorized	Missing or invalid API key. Ensure your `Authorization` header is correct.
402	insufficient_credits	Not enough credits for this operation. Buy a credit pack or upgrade your plan.
403	forbidden	API key is deactivated or lacks permission.
404	not_found	Resource not found. For URL endpoints, the source URL may be unsupported or unavailable.
409	conflict	Conflict (e.g., trying to create a resource that already exists).
422	validation_error	Request body failed validation. Check the `detail` field for field-level errors.
429	rate_limited	Too many requests. See Rate Limits & Pagination.
500	server_error	Internal server error. Retry the request. If persistent, contact support.
502	upstream_error	An upstream service (e.g., the video platform) returned an error.
503	service_unavailable	Service temporarily unavailable. Retry with exponential backoff.

Detailed Error Examples

401 — Invalid API Key

{
  "detail": "Invalid or missing API key"
}

402 — Insufficient Credits

{
  "detail": "Insufficient credits",
  "code": "insufficient_credits",
  "required": 3,
  "available": 1
}

404 — URL Not Supported

{
  "detail": "Could not extract info from URL: Unsupported URL"
}

422 — Validation Error

{
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429 — Rate Limited

{
  "detail": "Rate limit exceeded. Retry after 5 seconds.",
  "retry_after": 5
}

Error Handling Best Practices

Always check the HTTP status code before parsing the response body. For 4xx errors, the issue is with your request — check the detail field for guidance on what to fix. For 5xx errors, the issue is on our side — retry with exponential backoff (wait 1s, then 2s, then 4s, up to 30s).

For 402 (insufficient credits), your options are: buy a credit pack for immediate top-up, upgrade your plan for a higher monthly allowance, or wait for your credits to reset at the start of your next billing cycle.

For 429 (rate limited), respect the Retry-After header if present. Your rate limit depends on your plan tier. See the Rate Limits page for details.

Python Error Handling Example

import time
import requests

response = requests.post(
    "https://videoconduit.com/v1/download",
    headers={"Authorization": "Bearer vc_your_api_key"},
    json={"url": "https://example.com/video"},
)

if response.status_code == 200:
    job = response.json()
    print(f"Job created: {job['job_id']}")
elif response.status_code == 402:
    error = response.json()
    print(f"Need {error['required']} credits, have {error['available']}")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    time.sleep(retry_after)
    # Retry...
else:
    print(f"Error {response.status_code}: {response.json()['detail']}")