HTTP Status Codes and Solutions
All error codes returned by the ProxyTurk API, their meanings, and resolution suggestions. Use this reference to quickly resolve issues when you encounter errors.
import proxyturkfrom proxyturk.exceptions import ( AuthenticationError, RateLimitError, InsufficientCreditsError, BadRequestError, ServerError)client = proxyturk.Client(api_key="YOUR_API_KEY")def safe_scrape(url: str): try: response = client.scrape(url=url, formats=["markdown"]) return response.markdown except AuthenticationError: print("Invalid API key. Check your Dashboard.") return None except InsufficientCreditsError: print("Insufficient credits. Please top up.") return None except RateLimitError as e: retry_after = e.retry_after print(f"Rate limited. Retrying in {retry_after}s...") import time time.sleep(retry_after) return safe_scrape(url) except BadRequestError as e: print(f"Bad request: {e.message}") return None except ServerError: print("Server error. Retrying in 5s...") import time time.sleep(5) return safe_scrape(url)result = safe_scrape("https://example.com")ProxyTurk API uses standard HTTP status codes. Successful requests return 2xx, client errors return 4xx, and server errors return 5xx codes. Every error response contains a JSON error object:
{ "success": false, "error": { "code": "INVALID_REQUEST", "message": "URL parameter is required", "details": { ... } } }
Error responses always include a success: false field. The error.code field is a constant code that can be checked programmatically. The error.message field is a human-readable explanation.
The request contains invalid or missing parameters. This error occurs when a required parameter is missing, a parameter format is incorrect, or an invalid value is sent.
Common causes: - url parameter is missing or in an invalid format - formats array is empty or contains an unsupported format - extract.schema is not a valid JSON Schema - Body is not valid JSON
Solution: Compare your request parameters against the API reference. Ensure the URL starts with http:// or https://. Validate your JSON body with a validator tool.
Your account balance is insufficient or your credit limit has been reached. This error is returned when the credits required to process the request exceed your available balance.
Common causes: - Credit balance is zero - Monthly usage limit exceeded - Plan upgrade required
Solution: Check your credit balance from the Dashboard. Top up your balance or upgrade your plan. Enable auto-reload to ensure uninterrupted usage.
You do not have permission to access this resource. Your API key is valid but lacks the required permissions for the requested operation.
Common causes: - Accessing an endpoint not included in your plan (e.g., SERP endpoint on the free plan) - IP restriction: API key is restricted to specific IPs - Attempting to scrape a restricted URL
Solution: Check which endpoints your plan covers from the Dashboard. Review your IP restrictions. Verify whether the target URL is restricted.
The requested resource was not found. The endpoint URL is incorrect or you are trying to access a non-existent resource.
Common causes: - Typo in the endpoint URL - Querying with a non-existent job_id - Wrong API version (e.g., /v2/ instead of /v1/)
Solution: Ensure the API base URL is https://api.proxyturk.com/v1/. Compare the endpoint name with the API reference. Verify the job ID is correct.
Rate limit exceeded. Too many requests were sent in a short period. Each plan has different rate limits, and requests are rejected when the limit is exceeded.
Rate limit information is returned in the response headers: - X-RateLimit-Limit: Total allowed requests - X-RateLimit-Remaining: Remaining requests - X-RateLimit-Reset: Unix timestamp when the limit resets - Retry-After: Seconds to wait before retrying
Solution: Time your requests according to the Retry-After header. If you are using the SDK, automatic retry is enabled by default. Consider upgrading your plan if your request volume is consistently high. Batch your requests to use the rate limit more efficiently.
An unexpected error occurred on the server side. This error is not related to your request but is caused by a temporary issue in the ProxyTurk infrastructure.
Common causes: - Temporary server issue - Target site returned an unexpected response - Temporary infrastructure load spike
Solution: Wait a few seconds and retry the request. If the issue persists, check the system status at status.proxyturk.com. Contact our support team if you are consistently receiving 500 errors.
Questions about error codes
Read the Retry-After header from the response and wait for the specified duration. If you are using the SDK, the automatic retry mechanism is already active. Consider upgrading your plan if you are consistently hitting rate limits.
Verify from the Dashboard that the key is active. Ensure the header format is "Authorization: Bearer YOUR_KEY". If needed, revoke the key and generate a new one.
Check the system status at status.proxyturk.com. If it keeps happening for a specific URL, report it to the support team with the URL information. Temporary server issues are usually resolved within a few minutes.
API error messages are returned in English. The error.code field is for programmatic checks, while error.message provides a human-readable explanation. We recommend creating user-facing messages in your own language within your application.