The WebLinq API uses conventional HTTP response codes to indicate the success or failure of an API request:
  • 2xx indicates success
  • 4xx indicates an error that failed given the information provided
  • 5xx indicates an error with our servers

​
Error Response Formats

WebLinq uses two different error response formats depending on the type of error:

​
Validation Errors (422 Unprocessable Entity)

When request validation fails, you’ll receive a detailed error response with specific field-level issues:
Validation Error Format
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_type",
        "path": ["url"],
        "message": "Expected string, received number"
      },
      {
        "code": "too_small",
        "path": ["waitTime"],
        "message": "Number must be greater than or equal to 0"
      }
    ],
    "name": "ZodError"
  }
}

​
Other Errors (401, 404, 500, etc.)

For authentication, authorization, not found, and server errors, you’ll receive a simpler format:
Simple Error Format
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "authentication_required"
  }
}

​
Common HTTP Status Codes

​
200 OK

Request succeeded. The response will contain the requested data.

​
401 Unauthorized

Authentication required. You need to provide a valid API key. Example Response: 
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "authentication_required"
  }
}

​
404 Not Found

The requested resource doesn’t exist. Example Response: 
{
  "success": false,
  "error": {
    "message": "API key not found",
    "code": "not_found"
  }
}

​
422 Unprocessable Entity

Request validation failed. Check the issues array for specific field errors. Example Response: 
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_url",
        "path": ["url"],
        "message": "Must be a valid URL"
      }
    ],
    "name": "ZodError"
  }
}

​
429 Too Many Requests

Rate limit exceeded. Wait before making more requests. Example Response: 
{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Please try again later",
    "code": "rate_limit_exceeded"
  }
}

​
500 Internal Server Error

Something went wrong on our end. Try again later. Example Response: 
{
  "success": false,
  "error": {
    "message": "An unexpected error occurred",
    "code": "internal_server_error"
  }
}

​
Error Handling Best Practices

​
1. Always Check the success Field

const response = await fetch('/api/web/screenshot', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com' }),
});

const data = await response.json();

if (!data.success) {
  // Handle error
  console.error('API Error:', data.error);
  return;
}

// Use successful data
console.log('Screenshot taken:', data.data);

​
2. Handle Validation Errors Specifically

if (response.status === 422) {
  // Validation error - check individual field issues
  data.error.issues.forEach((issue) => {
    console.error(`Field '${issue.path.join('.')}': ${issue.message}`);
  });
} else {
  // Other error - display general message
  console.error(`Error (${data.error.code}): ${data.error.message}`);
}

​
Need Help?

If you encounter persistent errors, please contact our support team with:
  • The HTTP status code
  • The complete error response
  • Your request payload (without sensitive data)
  • The timestamp when the error occurred

Get Support

Contact our support team for assistance