Workflows

Error handling when creating orders

Robust error handling is essential when uploading orders to the TaxCloud API. Whether you’re uploading orders in bulk or sending them individually, gracefully managing failures ensures data consistency, reduces compliance risks, and prevents silent issues that could affect reporting and filing.

TaxCloud provides descriptive and structured error messages that help you quickly diagnose and resolve issues in your integration. This section outlines how to anticipate, interpret, and handle common error responses.

Common Error Types and What They Mean

Here are the most frequent error status codes you may encounter when uploading orders, along with their meanings and how to respond:

400 Bad Request

This indicates that the payload sent is malformed or does not conform to the expected schema.

Possible Causes

  • Missing required fields (e.g., customerID, cartID, or destination).
  • Invalid data types (e.g., price as a string instead of a number).
  • Unexpected or unsupported fields.

Resolution

  • Carefully validate your JSON structure before sending.
  • Refer to the Create Orders endpoint reference for field requirements.

422 Unprocessable Entity

This status means that the structure of the request is technically correct, but the contents are invalid or incomplete for processing.

Common Triggers

  • Address fields are incomplete or invalid.
  • Exemption fields are missing for an exempt order.

Resolution

  • Double-check each item in your items array.
  • Ensure all required customer and address information is included.
  • If using exemptions, verify that isExempt and/or exemptionId are properly set.

500 Internal Server Error

This response indicates a temporary issue on TaxCloud’s end.

Behavior

  • These are typically transient and resolve on their own.
  • Not usually caused by client-side issues.

Resolution

  • Implement a retry strategy with exponential backoff.
  • Log failed attempts with request metadata to enable future debugging.

Exponential Backoff Pattern (Example)

1import time
2import requests
3
4def upload_order(order_data):
5    retry_count = 0
6    backoff = 1  # start with 1 second
7
8    while retry_count < 5:
9        response = requests.post("https://api.v3.taxcloud.com/tax/connections/:connectionId/orders", json=order_data)
10        if response.status_code == 500:
11            print("Server error. Retrying...")
12            time.sleep(backoff)
13            retry_count += 1
14            backoff *= 2
15        else:
16            return response
17
18    raise Exception("Failed to upload order after multiple retries.")

Best Practices for Error Handling

  • Log all API responses, including success and error payloads. This is crucial for traceability during audits and support requests.
  • Validate your payloads locally before uploading (e.g., using a schema validation library).
  • Include order metadata (e.g., external order ID, timestamp) in your logs and requests to simplify debugging.

Next Steps

With robust error handling in place, you’re now ready to refund uploaded orders.