Error Codes Reference

Complete reference for all HTTP error codes returned by the URLert API and how to handle them.

Error Response Format

All API errors return a JSON response with a detail field containing the error information.

Always check the HTTP status code first, then parse the error response body for details.

HTTP Status Codes

401 Unauthorized

Authentication failed or API token is invalid

Common Causes:

• Missing Authorization header
• Invalid or expired API token
• Incorrect token format (missing "Bearer " prefix)

Example Response:

{
  "detail": "Invalid or missing API token"
}

How to Fix:

Include your API token in the Authorization header with the Bearer scheme: Authorization: Bearer u_sk_your_token. Regenerate your token from the Dashboard if it's invalid.

402 Payment Required

Your account balance is insufficient for this request

Common Causes:

• Account balance is lower than the cost of the requested operation
• Free trial credit has been exhausted

Example Response:

{
  "detail": "Insufficient balance. Required: $0.0200, Available: $0.0100"
}

How to Fix:

Add funds to your account from the Dashboard. The response includes your current balance and the amount required for the request.

403 Forbidden

Your organization account is not found or is inactive

Common Causes:

• Organization account has been deactivated

Example Response:

{
  "detail": "Organization not found or inactive"
}

How to Fix:

404 Not Found

The requested resource does not exist

Common Causes:

• Resource does not exist
• Invalid endpoint URL

Example Response:

{
  "detail": "Resource does not exist"
}

How to Fix:

Verify the ID is correct. Check that you're using the correct endpoint URL.

422 Unprocessable Entity

The request body contains invalid data

Common Causes:

• Invalid URL format
• Missing required fields
• Invalid data types

Example Response:

{
  "detail": [
    {
      "type": "url_parsing",
      "loc": ["body", "url"],
      "msg": "Input should be a valid URL, relative URL without a base",
      "input": "ht.il",
      "ctx": {
        "error": "relative URL without a base"
      }
    }
  ]
}

How to Fix:

Check the detail array for specific validation errors. Each error includes the field location (loc), error message (msg), and the invalid input value. Ensure URLs include a valid protocol (http:// or https://).

429 Too Many Requests

You have exceeded the rate limit for this endpoint

Common Causes:

• Exceeded per-minute rate limit for the endpoint
• Polling too frequently (less than 2-3 seconds between requests)

Example Response:

{
  "detail": {
    "error": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 42 seconds.",
    "limit": 10,
    "retry_after": 42
  }
}

How to Fix:

Wait for the duration specified in the retry_after field (in seconds) or the Retry-After header before making another request. See the Rate Limiting Guide for best practices.

500 Internal Server Error

An unexpected error occurred on our servers

Example Response:

{
  "detail": "An internal error occurred. Please try again later."
}

How to Fix:

These errors are typically temporary. Retry your request after a short delay (5-10 seconds). If the error persists, contact us at support@urlert.com.

504 Gateway Timeout

The request took too long to process

Common Causes:

• Analysis exceeded the API's timeout threshold
• Slow DNS/RDAP/SSL responses for the target domain

Example Response:

{
  "detail": "Analysis timeout"
}

How to Fix:

If a specific domain consistently times out, retry the request. If the issue persists, the target domain may have network issues preventing analysis.

Error Handling Best Practices

• Always check HTTP status codes before parsing the response body
• Implement exponential backoff for 429 and 500 errors (respect Retry-After header)
• Log error details for debugging (error code, message, and request context)
• Handle 402 errors gracefully by prompting users to add funds
• Don't retry 401, 403, 404, 422 errors without fixing the underlying issue
• Monitor your error rates to catch issues early