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.

Detailed Error Reference

401

Unauthorized

Authentication failed or API token is invalid.

Possible Causes

  • Missing Authorization header - The request is missing the required Authorization header.
  • Invalid or expired API token - The provided token is invalid or has expired.
  • Incorrect token format - The token format is incorrect (missing "Bearer " prefix).

Resolution

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.

Example Error Response

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

Payment Required

Your account balance is insufficient for this request.

Possible Causes

  • Insufficient funds - Account balance is lower than the cost of the requested operation.
  • Trial expired - Free trial credit has been exhausted.

Resolution

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

Example Error Response

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

Forbidden

Your organization account is not found or is inactive.

Possible Causes

  • Account deactivated - Organization account has been deactivated.

Resolution

Contact us at support@urlert.com for assistance with account status issues.

Example Error Response

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

Not Found

The requested resource does not exist.

Possible Causes

  • Resource missing - Resource does not exist.
  • Invalid URL - Invalid endpoint URL.

Resolution

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

Example Error Response

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

Unprocessable Entity

The request body contains invalid data.

Possible Causes

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

Resolution

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://).

Example Error 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"
      }
    }
  ]
}
429

Too Many Requests

You have exceeded the rate limit for this endpoint.

Possible Causes

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

Resolution

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.

Example Error Response

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

Internal Server Error

An unexpected error occurred on our servers.

Resolution

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.

Example Error Response

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

Gateway Timeout

The request took too long to process.

Possible Causes

  • Processing timeout - The request exceeded our internal processing threshold.
  • Infrastructure delay - Temporary system overhead during high-intensity operations.

Resolution

Gateway timeouts are typically internal system issues. Retry your request after a short delay. If the same request consistently returns 504, please contact us at support@urlert.com.

Example Error Response

{
  "detail": "Analysis timeout"
}

Error Handling Best Practices

Do

  • ✓ Check HTTP status codes first
  • ✓ Implement exponential backoff for 429/500
  • ✓ Log full error details for debugging

Don't

  • ✕ Parse body without checking status code
  • ✕ Retry client errors (400-404) blindly
  • ✕ Ignore rate limit headers