Errors

Possible errors and their meaning

Error Response Format

The Taxwire API returns errors in a standardized format, inspired by the JSON:API spec:

{
  "errors": [
    {
      "status": "422",
      "code": "validation_required_field",
      "title": "Missing quantity",
      "detail": "Please provide a value for the required quantity field",
      "source": {
        "pointer": "/data/attributes/line_items/0/quantity"
      }
    }
  ]
}

Each error object contains:

Field	Required	Description
status	Yes	HTTP status code as a string
code	Yes	Application-specific error code
title	Yes	A short, human-readable summary of the problem
detail	Yes	A human-readable explanation of the error
source.pointer	No	A pointer to the associated entity in the request document (only for validation errors)

Error Codes

The Taxwire API uses the following standardized error codes:

Category	Error Code	Description
System Errors	system_internal_error	An unexpected server error occurred
	system_service_unavailable	The service is temporarily unavailable
Validation Errors	validation_error	General validation error
	validation_required_field	A required field is missing
	validation_invalid_format	A field has an invalid format
Authentication Errors	auth_error	General authentication error
	auth_api_key_not_found	The provided API key was not found
	auth_api_key_expired	The provided API key has expired
Other Errors	rate_limit_error	Rate limit exceeded
	conflict	Resource conflict

HTTP Status Codes

400 Bad Request

The request is invalid. The error response will include specific validation errors.

Common error codes: validation_error

Action: Check your request parameters and ensure they match the API specifications.

401 Unauthorized

The request is unauthorized. This can happen when the API key provided is invalid or expired.

Common error codes: auth_error, auth_api_key_not_found, auth_api_key_expired

Action: Verify your API key is valid and active.

403 Forbidden

The request is forbidden. This can happen for a number of reasons:

• The API key header is missing
• The API key does not have access to the resource

Common error codes: auth_error

Action: Ensure you’re using the correct API key with appropriate permissions.

404 Not Found

The requested resource was not found. This can happen for a number of reasons:

• The resource does not exist
• The resource is not accessible by the API key

Action: Check that the resource identifier is correct.

409 Conflict

The request could not be processed due to a conflict with the current state of the resource. This could happen if you have sent the same transaction more than once.

Common error codes: conflict

Action: Resolve the conflict and try again.

422 Unprocessable Entity

The request contains valid data but the server cannot process it. This typically happens when:

• The request is missing a required parameter
• Some data in the request is invalid

Common error codes: validation_error, validation_required_field, validation_invalid_format

Action: Check the error details for specific information about what needs be corrected.

429 Too Many Requests

The request was rate limited. This means you have made too many requests in a short period of time.

Common error codes: rate_limit_error

Action: The response will include a Retry-After header with the number of seconds to wait before making the next request. Implement exponential backoff in your client.

For example, a rate-limited response would include this header:

Retry-After: 30

This indicates you should wait at least 30 seconds before making another request. Your client should respect this header and implement proper backoff strategies.

500 Internal Server Error

The server encountered an error while processing the request.

Common error codes: system_internal_error

Action: This is likely a bug and should be reported to support if it persists.

Error Examples

Internal Server Error

{
    "errors": [
        {
            "status": "500",
            "code": "system_internal_error",
            "title": "Internal Error",
            "detail": "An unexpected error occurred. Our team has been notified."
        }
    ]
}

Rate Limit Error

{
    "errors": [
        {
            "status": "429",
            "code": "rate_limit_error",
            "title": "Too Many Requests",
            "detail": "Rate limit exceeded"
        }
    ]
}

Validation Errors

{
    "errors": [
        {
            "status": "422",
            "code": "validation_required_field",
            "title": "Missing quantity",
            "detail": "Please provide a value for the required quantity field",
            "source": {
                "pointer": "/data/attributes/line_items/0/quantity"
            }
        },
        {
            "status": "422",
            "code": "validation_invalid_format",
            "title": "Invalid quantity format",
            "detail": "Input should be a valid string",
            "source": {
                "pointer": "/data/attributes/line_items/1/quantity"
            }
        }
    ]
}

API Key Error

{
    "errors": [
        {
            "status": "401",
            "code": "auth_api_key_not_found",
            "title": "API key not found.",
            "detail": "The provided API key was not found. Please check your credentials."
        }
    ]
}

Sample Error Handling

Here is a simple example of how to handle errors in Python:

Python

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

url = "https://api.taxwire.com/calculations"
headers = {
    "X-API-Key": "REPLACE_WITH_YOUR_API_KEY",
    "Taxwire-Version": "hydrogen.2025-04-15",
    "Content-Type": "application/json",
}
payload = {
    "line_items": [
        {
            "quantity": "1",
            "unit_price": "10000",
            "customer": {
                "address": {
                    "country": "US",
                    "state": "CA",
                    "postal_code": "94104",
                    "city": "San Francisco",
                }
            }
        }
    ]
}

retry_strategy = Retry(
    total=5,  # Maximum number of retries
    backoff_factor=2,  # Exponential backoff (2s, 4s, 8s, etc.)
    status_forcelist=[429, 500, 502, 503, 504],  # Retries for rate limiting & transient errors
    allowed_methods={"POST"},
    respect_retry_after_header=True,  # Uses `Retry-After` if provided
)

# Create a session and mount the retry adapter
session = requests.Session()
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)

# Make the request using the session
response = session.post(url, json=payload, headers=headers)
response.json()