Error Handling

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

Overview

User

API Keys

Web

Files

System

Web v2

Error Response Formats

Validation Errors (422 Unprocessable Entity)

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

Common HTTP Status Codes

200 OK

401 Unauthorized

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Error Handling Best Practices

1. Always Check the `success` Field

2. Handle Validation Errors Specifically

Need Help?

Get Support

​Error Response Formats

​Validation Errors (422 Unprocessable Entity)

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

​Common HTTP Status Codes

​200 OK

​401 Unauthorized

​404 Not Found

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Error Handling Best Practices

​1. Always Check the success Field

​2. Handle Validation Errors Specifically

​Need Help?

Get Support

Error Response Formats

Validation Errors (422 Unprocessable Entity)

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

Common HTTP Status Codes

200 OK

401 Unauthorized

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Error Handling Best Practices

1. Always Check the `success` Field

2. Handle Validation Errors Specifically

Need Help?