Error handling
TaxStreem uses standard HTTP status codes and structured JSON error responses.
| Field | Type | Description |
|---|---|---|
| 400 | Bad Request | Invalid request body — missing required fields or invalid values. |
| 401 | Unauthorized | Invalid or missing API key. |
| 403 | Forbidden | API key does not have permission for this resource. |
| 409 | Conflict | Duplicate filing — same idempotency key already processed. |
| 429 | Too Many Requests | Rate limit exceeded. Retry with exponential backoff. |
| 500 | Internal Server Error | Unexpected server error. Retry after a short delay. |
Error response shape
{
"status": "error",
"responseCode": 400,
"message": "INVALID_REQUEST: encryptedPayload is required",
"errors": [
{ "field": "encryptedPayload", "message": "Field is required" }
]
}Idempotency:All filing endpoints support an
Idempotency-Key header. Submitting the same key twice returns the original result — preventing duplicate filings on retry.