Guide

Errors and retries

Understand API problem responses, HTTP status codes, retryable failures, and when to reuse an idempotency key.

Read the problem response

Errors use application/problem+json. Branch on the stable code, keep the request_id for support, and check retryable.

HTTP	Example code	What to do
`400`	`invalid_request`	Fix the request shape or field named in the problem.
`401`	`invalid_api_key`	Check that the bearer key is valid and active.
`404`	`resource_not_found`	Check the resource ID and workspace.
`409`	`idempotency_conflict`	Reuse the original request or use a new key for a new request.
`422`	`adjustment_exceeds_original`	Check the stored transaction and remaining refundable amount.
`429`	`rate_limit_exceeded`	Wait for Retry-After before retrying.
`503`	`runtime_not_configured`	Retry later when the dependency is available.

400 Bad Requestapplication/problem+json

{
  "type": "https://api.salestaxcalculatorapi.com/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request body must be valid JSON.",
  "instance": "/v1/calculations",
  "code": "invalid_request",
  "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9",
  "retryable": false
}

Retry only when the API says to

For retryable failures, honor Retry-After or retry_after_seconds. Repeat the same body with the same idempotency key for a create request.