Error Codes

This guide provides a comprehensive list of error codes that you might encounter when using the Scrapezy API, along with explanations and recommended solutions.

Error Response Format

All API errors follow a consistent format:

{
  "error": "A human-readable description of the error"
}

Authentication Errors (4xx)

401 Unauthorized

INVALID_API_KEY

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "error": "Invalid API Key"
}

Causes:

• Missing API key in the request header
• Invalid API key format
• Expired API key
• Revoked API key

Solution:

• Check if you're including the API key in the x-api-key header
• Verify your API key is valid in the dashboard
• Generate a new API key if expired
• Contact support if you believe this is an error

402 Payment Required

INSUFFICIENT_CREDITS

HTTP/1.1 402 Payment Required
Content-Type: application/json
 
{
  "error": "Insufficient credits to perform extraction"
}

Causes:

• No credits remaining in your account
• Attempted to perform a paid operation without credits

Solution:

• Purchase more credits from your dashboard
• Check your credit usage in the billing section
• Consider upgrading your plan for more credits

403 Forbidden

INSUFFICIENT_PERMISSIONS

HTTP/1.1 403 Forbidden
Content-Type: application/json
 
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key doesn't have permission to perform this action"
  }
}

Causes:

• API key lacks required permissions
• Attempting to access resources you don't own
• Attempting to modify read-only resources

Solution:

• Check your API key permissions in the dashboard
• Request necessary permissions from your organization admin
• Use an API key with appropriate permissions

Resource Errors (4xx)

404 Not Found

RESOURCE_NOT_FOUND

HTTP/1.1 404 Not Found
Content-Type: application/json
 
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found"
  }
}

Causes:

• Invalid resource ID
• Resource has been deleted
• Resource doesn't exist

Solution:

• Verify the resource ID is correct
• Check if the resource still exists
• Ensure you have access to the resource

400 Bad Request

INVALID_REQUEST

HTTP/1.1 400 Bad Request
Content-Type: application/json
 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid"
  }
}

Causes:

• Missing required fields
• Invalid field values
• Malformed JSON
• Invalid query parameters

Solution:

• Check the API documentation for required fields
• Validate your request payload
• Ensure JSON is properly formatted
• Verify query parameter types and values

Server Errors (5xx)

500 Internal Server Error

INTERNAL_SERVER_ERROR

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
 
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred"
  }
}

Causes:

• Unexpected server-side error
• Database connection issues
• Third-party service failures

Solution:

• Retry the request after a short delay
• Check our status page for any ongoing issues
• Contact support if the problem persists

Best Practices for Error Handling

1. Always Check Status Codes

   • Don't assume requests will succeed
   • Handle both success and error cases
   • Check for specific error codes

2. Implement Retry Logic

   • Use exponential backoff for retries
   • Respect the Retry-After header
   • Don't retry on client errors (4xx)

3. Log Errors Appropriately

   • Log error responses for debugging
   • Include request IDs in logs
   • Monitor error rates

4. User-Friendly Error Messages

   • Parse error messages for display
   • Show appropriate user feedback
   • Provide clear next steps

Next Steps

• Authentication Guide
• Rate Limiting Guide
• Contact Support