Error Codes

Starting with API version 2026-01-01, error responses use a simplified, consistent format.

Error Response Format

All errors return a JSON object with three fields:

{
  "code": 400,
  "type": "ZIP_STATE_MISMATCH",
  "message": "Unable to create calculation. address_zip_code 92037 not found in the address_province TN. Ensure zip is up to date and formed correctly."
}

Field	Type	Description
`code`	integer	HTTP status code
`type`	string	Machine-readable error type (use this for programmatic handling)
`message`	string	Human-readable description of the error

Previous API versions used a nested error object. The 2026-01-01 format is flattened for easier parsing.

Error Types Reference

Validation Errors

These errors occur when request data is invalid or malformed.

Type	Description
`ERROR`	Generic error
`MISSING_FIELD`	A required field was not provided
`INCORRECT_TYPE`	A field has the wrong data type
`UNRECOGNIZED_FIELD`	An unknown field was included in the request
`NEGATIVE_NUMBER_REQUIRED`	Field requires a negative number
`POSITIVE_NUMBER_REQUIRED`	Field requires a positive number
`INVALID_EMAIL`	Email address format is invalid

Address Errors

These errors relate to address validation issues.

Type	Description
`MALFORMED_ADDRESS`	Address format is invalid or incomplete
`ZIP_STATE_MISMATCH`	ZIP/postal code does not match the provided state/province
`MISSING_ORIGIN_ADDRESS`	Origin address is required but not provided (check merchant default address)
`INVALID_COUNTRY_CODE`	Country code is not recognized (use ISO 3166-1 alpha-2)

Product Errors

These errors relate to product operations.

Type	Description
`PRODUCT_NOT_FOUND`	The specified product ID does not exist
`DUPLICATE_PRODUCT`	A product with this reference ID already exists
`INVALID_TAX_CODE`	The product tax code is not valid
`INVALID_PRODUCT_CATEGORY`	The product category is not recognized

Customer Errors

These errors relate to customer operations.

Type	Description
`CUSTOMER_NOT_FOUND`	The specified customer ID does not exist
`DUPLICATE_CUSTOMER`	A customer with this reference ID already exists

Merchant Errors

These errors relate to merchant operations (new in 2026-01-01).

Type	Description
`MERCHANT_NOT_FOUND`	The specified merchant ID does not exist
`DUPLICATE_MERCHANT`	A merchant with this reference ID already exists
`MERCHANT_CREATION_FAILED`	Failed to create the merchant
`MERCHANT_UPDATE_FAILED`	Failed to update the merchant

Calculation Errors

These errors relate to tax calculation operations.

Type	Description
`CALCULATION_NOT_FOUND`	The specified calculation ID does not exist
`CALCULATION_EXPIRED`	The calculation has expired and can no longer be used
`INVALID_CURRENCY_CODE`	Currency code is not supported (see supported currencies)

Transaction Errors

These errors relate to transaction operations.

Type	Description
`TRANSACTION_NOT_FOUND`	The specified transaction ID does not exist
`TRANSACTION_ALREADY_EXISTS`	A transaction with this calculation ID already exists
`REFERENCE_ORDER_ID_ALREADY_EXISTS`	A transaction with this reference order ID already exists

HTTP Status Codes

Code	Meaning
`400`	Bad Request - Invalid parameters or validation error
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Resource does not exist
`409`	Conflict - Resource already exists (duplicates)
`422`	Unprocessable Entity - Request understood but cannot be processed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Handling Errors

Example Error Handling

try {
  const response = await fetch('https://api.numeralhq.com/tax/calculations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'X-API-Version': '2026-01-01',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(calculationData)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.type) {
      case 'ZIP_STATE_MISMATCH':
        // Prompt user to verify their address
        break;
      case 'PRODUCT_NOT_FOUND':
        // Create the product first
        break;
      case 'CALCULATION_EXPIRED':
        // Request a new calculation
        break;
      default:
        console.error(`Error: ${error.message}`);
    }
  }
} catch (err) {
  // Handle network errors
}

Best Practices

Always check the type field for programmatic error handling
Display the message field to users when appropriate
Log the full error response for debugging
Handle specific error types rather than just checking status codes

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

Error Codes

Error Codes

Error Response Format

Error Types Reference

Validation Errors

Address Errors

Product Errors

Customer Errors

Merchant Errors

Calculation Errors

Transaction Errors

HTTP Status Codes

Handling Errors

Example Error Handling

Best Practices

​Error Codes

​Error Response Format

​Error Types Reference

​Validation Errors

​Address Errors

​Product Errors

​Customer Errors

​Merchant Errors

​Calculation Errors

​Transaction Errors

​HTTP Status Codes

​Handling Errors

​Example Error Handling

​Best Practices

Error Codes

Error Response Format

Error Types Reference

Validation Errors

Address Errors

Product Errors

Customer Errors

Merchant Errors

Calculation Errors

Transaction Errors

HTTP Status Codes

Handling Errors

Example Error Handling

Best Practices