> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> All Avatcado API error codes at a glance

# Error Reference

Every error response includes a machine-readable `code`, a human-readable `message`, and a `docs_url` linking to the relevant page below.

```json theme={null}
{
  "error": {
    "code": "invalid_vat_format",
    "message": "The VAT number format is invalid. Expected format: CC123456789",
    "docs_url": "https://docs.avatcado.com/errors/invalid_vat_format"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## All error codes

| Code                                                                             | HTTP Status | Description                                                                           |
| -------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- |
| [`missing_parameter`](/errors/missing_parameter)                                 | 400         | Required query parameter `vat_number` not provided                                    |
| [`invalid_vat_format`](/errors/invalid_vat_format)                               | 422         | VAT number format unrecognized or country code unsupported                            |
| [`unauthorized`](/errors/unauthorized)                                           | 401         | Invalid or missing API key                                                            |
| [`rate_limit_exceeded`](/errors/rate_limit_exceeded)                             | 429         | Monthly quota exhausted                                                               |
| [`burst_limit_exceeded`](/errors/burst_limit_exceeded)                           | 429         | Per-minute burst limit exceeded                                                       |
| [`upstream_unavailable`](/errors/upstream_unavailable)                           | 503         | Upstream service (VIES, HMRC, BFS, BRREG, or ABR) is unreachable or returned an error |
| [`tier_insufficient`](/errors/tier_insufficient)                                 | 403         | Feature requires a higher tier (e.g. batch validation on Free)                        |
| [`validation_error`](/errors/validation_error)                                   | 422         | Request body validation failed (e.g. batch endpoint)                                  |
| [`invalid_json`](/errors/invalid_json)                                           | 400         | Request body contains malformed JSON                                                  |
| [`not_found`](/errors/not_found)                                                 | 404         | Requested resource not found (e.g. unknown country code for rates)                    |
| [`forbidden`](/errors/forbidden)                                                 | 403         | Access to this resource is forbidden (e.g. demo key restriction)                      |
| [`key_limit_reached`](/errors/key_limit_reached)                                 | 403         | Maximum number of API keys reached for this account                                   |
| [`key_revoked`](/errors/key_revoked)                                             | 409         | The API key has already been revoked                                                  |
| [`internal_error`](/errors/internal_error)                                       | 500         | An unexpected server error occurred                                                   |
| [`upstream_member_state_unavailable`](/errors/upstream_member_state_unavailable) | 503         | Specific EU member state VIES service is unavailable                                  |
| [`webhook_not_configured`](/errors/webhook_not_configured)                       | 400         | No webhook URL configured for async validation                                        |

## Handling errors with the SDKs

The `@avatcado/node` and `avatcado` (Python) SDKs provide typed error classes so you can match on specific error types. The Node.js SDK returns `{ data, error }` from every method, while the Python SDK raises exceptions.

<CodeGroup>
  ```typescript @avatcado/node theme={null}
  import Avatcado, {
    RateLimitError,
    UpstreamError,
    AuthenticationError,
    ValidationError,
    AvatcadoError,
  } from "@avatcado/node";

  const avatcado = new Avatcado("avat_live_your_api_key");
  const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });

  if (error) {
    if (error instanceof RateLimitError) {
      console.log(`Retry after ${error.retryAfter} seconds`);
    } else if (error instanceof UpstreamError) {
      console.log(`Retry after ${error.retryAfter} seconds`);
    } else if (error instanceof AuthenticationError) {
      console.log(error.message);
    } else if (error instanceof ValidationError) {
      console.log(error.message);
      console.log(error.details); // Array<{ field, message }> | null
    } else {
      // AvatcadoError base class
      console.log(`${error.code}: ${error.message}`);
      console.log(error.docsUrl);
    }
  }
  ```

  ```python Python theme={null}
  from avatcado import Avatcado, RateLimitError, UpstreamError, AuthenticationError, ValidationError, AvatcadoError

  avatcado = Avatcado("avat_live_your_api_key")

  try:
      result = avatcado.vat.validate("NL123456789B01")
  except RateLimitError as e:
      print(f"Retry after {e.retry_after} seconds")
  except UpstreamError as e:
      print(f"Retry after {e.retry_after} seconds")
  except AuthenticationError as e:
      print(e.message)
  except ValidationError as e:
      print(e.message)
      print(e.details)  # list of dicts or None
  except AvatcadoError as e:
      print(f"{e.code}: {e.message}")
      print(e.docs_url)
  ```
</CodeGroup>

Every error has `code`, `message`, and `docsUrl` (Node.js) / `docs_url` (Python) properties matching the [error codes](#all-error-codes) above.