Skip to main content

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."
}
FieldTypeDescription
codeintegerHTTP status code
typestringMachine-readable error type (use this for programmatic handling)
messagestringHuman-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.
TypeDescription
ERRORGeneric error
MISSING_FIELDA required field was not provided
INCORRECT_TYPEA field has the wrong data type
UNRECOGNIZED_FIELDAn unknown field was included in the request
NEGATIVE_NUMBER_REQUIREDField requires a negative number
POSITIVE_NUMBER_REQUIREDField requires a positive number
INVALID_EMAILEmail address format is invalid

Address Errors

These errors relate to address validation issues.
TypeDescription
MALFORMED_ADDRESSAddress format is invalid or incomplete
ZIP_STATE_MISMATCHZIP/postal code does not match the provided state/province
MISSING_ORIGIN_ADDRESSOrigin address is required but not provided (check merchant default address)
INVALID_COUNTRY_CODECountry code is not recognized (use ISO 3166-1 alpha-2)

Product Errors

These errors relate to product operations.
TypeDescription
PRODUCT_NOT_FOUNDThe specified product ID does not exist
DUPLICATE_PRODUCTA product with this reference ID already exists
INVALID_TAX_CODEThe product tax code is not valid
INVALID_PRODUCT_CATEGORYThe product category is not recognized

Customer Errors

These errors relate to customer operations.
TypeDescription
CUSTOMER_NOT_FOUNDThe specified customer ID does not exist
DUPLICATE_CUSTOMERA customer with this reference ID already exists

Merchant Errors

These errors relate to merchant operations (new in 2026-01-01).
TypeDescription
MERCHANT_NOT_FOUNDThe specified merchant ID does not exist
DUPLICATE_MERCHANTA merchant with this reference ID already exists
MERCHANT_CREATION_FAILEDFailed to create the merchant
MERCHANT_UPDATE_FAILEDFailed to update the merchant

Calculation Errors

These errors relate to tax calculation operations.
TypeDescription
CALCULATION_NOT_FOUNDThe specified calculation ID does not exist
CALCULATION_EXPIREDThe calculation has expired and can no longer be used
INVALID_CURRENCY_CODECurrency code is not supported (see supported currencies)

Transaction Errors

These errors relate to transaction operations.
TypeDescription
TRANSACTION_NOT_FOUNDThe specified transaction ID does not exist
TRANSACTION_ALREADY_EXISTSA transaction with this calculation ID already exists
REFERENCE_ORDER_ID_ALREADY_EXISTSA transaction with this reference order ID already exists

HTTP Status Codes

CodeMeaning
400Bad Request - Invalid parameters or validation error
401Unauthorized - Invalid or missing API key
404Not Found - Resource does not exist
409Conflict - Resource already exists (duplicates)
422Unprocessable Entity - Request understood but cannot be processed
429Too Many Requests - Rate limit exceeded
500Internal 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

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