Error Handling

Complete guide to handling errors from the TokenSniped API.

HTTP Status Codes

Code	Meaning	Action
`200`	Success	Process the result
`400`	Bad Request	Fix your request parameters
`401`	Unauthorized	Check your API key
`402`	Insufficient Credits	Add more credits
`403`	Forbidden	Check resource ownership
`404`	Not Found	Check the request ID
`429`	Rate Limited	Wait and retry
`500`	Server Error	Retry with backoff

Error Response Format

All errors follow this structure:

{
  "error": "Error Type",
  "message": "Human-readable description",
  "details": "Additional context (optional)"
}

Common Errors

Authentication Errors (401)

Missing API Key

{
  "error": "Unauthorized",
  "message": "API key required. Use: Authorization: Bearer <api_key>"
}

Solution: Add the Authorization header:

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}

Solution:

Check for typos in your key

Ensure the key is active in your dashboard

Generate a new key if needed

Disabled API Key

{
  "error": "Unauthorized",
  "message": "API key is disabled"
}

Solution: Re-enable the key in Dashboard → API Keys

Validation Errors (400)

Missing Required Field

{
  "error": "Validation Error",
  "message": "Invalid request body",
  "details": "sitekey is required"
}

Solution: Check the API docs for required fields

Invalid Field Format

{
  "error": "Validation Error",
  "message": "Invalid request body",
  "details": "url must be a valid URL"
}

Solution: Ensure URLs include protocol (https://)

Credit Errors (402)

Insufficient Credits

{
  "error": "Insufficient Credits",
  "message": "This request requires 0.5 credits, but you only have 0.25 credits",
  "required": 0.5,
  "available": 0.25,
  "topUpUrl": "/dashboard/billing"
}

Solution:

Add credits via card or crypto

Claim your free daily credits

Wait for daily reset if using free tier

Rate Limit Errors (429)

Rate Limit Exceeded

{
  "error": "Rate Limit Exceeded",
  "message": "Rate limit of 60 requests per minute exceeded",
  "retryAfter": 45
}

Headers included:

RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 1699900000
Retry-After: 45

Solution:

Increase limits: Edit your API key in the dashboard to increase RPM/RPD limits.

Solve Errors (500)

When a captcha fails to solve, you get:

{
  "success": false,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Timeout waiting for challenge",
  "solve_time_ms": 30000
}

Note: Failed solves are not charged.

Common solve errors:

Error	Cause	Solution
`Timeout waiting for challenge`	Challenge took too long	Increase timeout, try again
`Invalid captcha_id`	Wrong captcha ID	Re-extract from target page
`Challenge not found`	Captcha not present	Verify URL has captcha
`Proxy connection failed`	Bad proxy	Check proxy credentials/status
`Page load failed`	Target site down	Check if site is accessible

Handling Errors in Code

Python

JavaScript

Retry Strategy

Implement exponential backoff for transient errors:

Getting Help

If you encounter persistent errors:

Check the status page for outages

Search our Discord for similar issues

Email [email protected] with:

Your request_id

The error message

The request parameters (without sensitive data)

HTTP Status Codes#

Error Response Format#

Common Errors#

Authentication Errors (401)#

Validation Errors (400)#

Credit Errors (402)#

Rate Limit Errors (429)#

Solve Errors (500)#

Handling Errors in Code#

Python#

JavaScript#

Retry Strategy#

Getting Help#

HTTP Status Codes

Error Response Format

Common Errors

Authentication Errors (401)

Validation Errors (400)

Credit Errors (402)

Rate Limit Errors (429)

Solve Errors (500)

Handling Errors in Code

Python

JavaScript

Retry Strategy

Getting Help