Error Handling

Complete reference for all error types and how to handle them.

When an error occurs, the API returns a JSON response with success: false, a human-readable error message, and a machine-readable error_type. All failed requests are automatically refunded.

json

{
  "success": false,
  "error": "Could not extract content from this page",
  "error_type": "EMPTY_CONTENT"
}

Authentication Errors

Status	Type	Message
`401`	`AUTH_ERROR`	Missing, invalid, or deactivated API key
`402`	`CREDITS_EXHAUSTED`	Insufficient credits or per-key limit reached
`429`	`RATE_LIMITED`	Rate limit exceeded (120 requests per minute)

Validation Errors

Status	Type	Message
`400`	`VALIDATION_ERROR`	Invalid request parameters (missing url, invalid type, etc.)

Network Errors

Status	Type	Message
`502`	`CONNECTION_ERROR`	Failed to connect to the target URL
`504`	`CONNECTION_TIMEOUT`	Connection to target URL timed out
`504`	`READ_TIMEOUT`	Target server took too long to respond
`502`	`TOO_MANY_REDIRECTS`	Too many redirects on the target URL
`502`	`HTTP_ERROR`	Target server returned an error

Content Errors

Status	Type	Message
`422`	`EMPTY_CONTENT`	Could not extract content from this page
`504`	`PAGE_TIMEOUT`	Page took too long to load
`502`	`PAGE_LOAD_FAILED`	Failed to load page content

YouTube Errors

These errors are specific to the Transcript API.

Status	Type	Message
`422`	`TRANSCRIPT_UNAVAILABLE`	Transcript is not available for this video
`422`	`VIDEO_UNAVAILABLE`	This video is unavailable or private
`429`	`RATE_LIMITED`	Rate limited by the target service

Internal Errors

Status	Type	Message
`500`	`INTERNAL_ERROR`	An unexpected error occurred. Contact support if persistent.

Handling Errors

Always check the success field before processing results.
Use error_type for programmatic error handling, not the error message.
All failed requests are automatically refunded. No credits are charged.
For CONNECTION_ERROR and PAGE_TIMEOUT, consider retrying with a delay.
For RATE_LIMITED, wait before retrying.
For CREDITS_EXHAUSTED, purchase more credits at pay.bikal.co.

Next:Scrape API Reference →