Skip to main content

​
Overview

This page consolidates all error responses you may encounter when using the Converso Audio Extraction API.
Each error includes:
  • Error code
  • HTTP status
  • Meaning / cause
  • Suggested solution
All endpoints follow the standard response envelope: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": "Optional extra information"
  }
}

​
Authentication Errors

CodeHTTP StatusDescriptionSuggested Action
UNAUTHORIZED401API key missing or invalidVerify your API key in X-API-Key header
FORBIDDEN403API key does not have accessCheck subscription plan and endpoint permissions

​
Request Errors

CodeHTTP StatusDescriptionSuggested Action
INVALID_REQUEST400Request payload invalid or missing required fieldsValidate JSON body and required fields
INVALID_SOURCE400Video source type or URL is invalidCorrect source.type and source.url
INVALID_JOB_ID400Job ID format invalidUse valid job_<16 hex> ID
TOO_MANY_JOBS400Batch exceeds max limit (10 jobs)Reduce batch size
INVALID_OUTPUT400Output format or options invalidCorrect output.format, quality, bitrate

​
Job & Processing Errors

CodeHTTP StatusDescriptionSuggested Action
JOB_NOT_FOUND404Job ID does not existVerify the job ID returned from POST /v1/extract
JOB_NOT_COMPLETED202Job not finished yetPoll status endpoint or wait for webhook
EXTRACTION_FAILED200/202Audio extraction failedCheck video format, codecs, or try again
DOWNLOAD_FAILED200/202Unable to download video from URLVerify the URL is public and reachable
INVALID_VIDEO400Video file corrupted or unsupportedProvide a valid video file
FILE_EXPIRED410Extracted file no longer availableDownload file immediately after completion

​
System & Server Errors

CodeHTTP StatusDescriptionSuggested Action
QUEUE_FULL503Processing queue is temporarily fullRetry after a few seconds
SERVICE_UNAVAILABLE503API temporarily unavailableRetry later or check status page
INTERNAL_ERROR500Unexpected server errorContact support with jobId and request details

​
Webhook Errors

CodeDescriptionSuggested Action
INVALID_WEBHOOKWebhook URL is unreachable or invalidVerify URL is public and responds with 2xx
WEBHOOK_FAILEDWebhook delivery failedRetry webhook delivery manually or check endpoint logs

​
Example Error Response

{
  "success": false,
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Audio extraction failed due to unsupported codec",
    "details": "Video codec VP9 is not supported in FLAC output"
  }
}

​
Best Practices

  • Always check the success field before processing responses
  • Implement retry logic for transient errors (QUEUE_FULL, SERVICE_UNAVAILABLE)
  • Validate request payloads to avoid INVALID_REQUEST and INVALID_OUTPUT
  • Poll or use webhooks instead of repeated failed downloads
  • Log errors with jobId for support troubleshooting

​
Next Step

API Introduction

Return to the Converso Audio Extraction API overview.
© Converso Empire. All rights reserved.