Errors

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
	`request_too_large`	The request body is too large

HTTP Status Codes

400 Bad Request

The request is invalid. The error response will include specific validation errors. The API also returns 400 when you create a transaction with a reference_id that already exists in your account. See Create transaction. 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 conflicts with a record that already exists, or it matches more than one record. The API returns 409 when:

You create a customer or product whose key is already taken
A product preset leaves out source_account_id, and its id exists in more than one connected account

A transaction with a reference_id that already exists returns 400, not 409. See Create transaction. Common error codes: conflict Action: Resolve the conflict and try again.

413 Request Too Large

The request body is larger than the API accepts, which is 5 MB. The API refuses it before reading it, so nothing is processed. Common error codes: request_too_large Action: Split the request into smaller ones. For example, send a large list of customers as several POST /customers/batch requests.

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
The currency is one we do not support
A credit’s parent_transaction_id is not one of your transactions
A credit’s sale, or an earlier credit against it, is still a draft (credit_remainder_unknown, see the FAQ)
A transaction request contains a NUL character (\u0000)

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. See Rate limits for the limit and how to raise it. 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: 1

This indicates you should wait at least 1 second 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()

Getting Started

Guides

Transaction flows

API details

Calculations

Transactions

Customers

Certificates

Jurisdictions

Product Tax Codes (PTC) & Attributes

Products

Resources

Error Response Format

Error Codes

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

413 Request Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Error Examples

Internal Server Error

Rate Limit Error

Validation Errors

API Key Error

Sample Error Handling

​Error Response Format

​Error Codes

​HTTP Status Codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​413 Request Too Large

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Error Examples

​Internal Server Error

​Rate Limit Error

​Validation Errors

​API Key Error

​Sample Error Handling

Error Response Format

Error Codes

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

413 Request Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Error Examples

Internal Server Error

Rate Limit Error

Validation Errors

API Key Error

Sample Error Handling