Errors
Understand Partner API error handling.
The Partner API returns standard HTTP status codes and JSON error responses.
Error envelope
{
"error": {
"code": "forbidden",
"message": "Request is not allowed."
}
}Messages are intentionally conservative.
For tenant-boundary failures, Taiga avoids returning details that could reveal whether an out-of-scope billing object exists.
Field-level validation errors
Validation failures Taiga detects before submitting a request for billing return
422 with an errors array naming each offending field. expected and
received are included when the correct value is known.
{
"message": "Provider fields failed validation; correct the listed fields and retry",
"errors": [
{
"field": "provider_type",
"message": "provider_type must be ORGANIZATION: the NPI registry lists 1962748244 as an organization (Type 2) provider",
"expected": "ORGANIZATION",
"received": "INDIVIDUAL"
}
]
}Status codes
| Status | Class | Meaning |
|---|---|---|
400 | Client | Malformed request, unsupported organization override, or missing fields |
401 | Auth | Bearer token is missing, malformed, or expired |
403 | Auth | Credential or organization is not allowed to perform the request |
404 | Client | Route or resource is not available to the credential |
409 | Client | Request conflicts with current resource state |
422 | Validation | One or more request fields failed validation |
429 | Rate limit | The credential is being rate limited |
500 | Server | Unexpected Taiga error |
502 | Integration | Taiga could not safely complete the upstream billing operation |
Retry guidance
Retry only transient failures. 429, 500, 502, network timeouts.
Use exponential backoff. Start small (250–500 ms) and double up to a cap (e.g. 30 s).
Cap the retry count. Surface the original error after the cap so callers can react.
Don't retry validation failures. 400, 401, 403, 422 won't get
better without changing the request or credentials.
Request IDs
Capture the response request ID in your logs.
It helps Taiga support trace a request without asking you to share PHI. Request IDs are safe to log.
Secret handling
Never log secrets or PHI.
Never log client secrets, bearer tokens, patient data, or full request bodies. Store partner credentials in a secret manager and rotate them if exposed.