Skip to navigation
Guides

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. A 404 on a resource you do not hold is deliberately identical to a 404 on one that does not exist.

Scope errors

When a request names a billing provider NPI your credential does not cover, the 403 includes an errors array naming the field, the value you sent, and the NPIs the credential does cover. Every one of those is something you already hold, so reporting them reveals nothing; it turns a mistyped digit into a fix you can make without opening a support ticket.

{
  "message": "Billing provider is outside this credential's scope",
  "errors": [
    {
      "field": "billing_provider_npi",
      "message": "billing_provider_npi is outside this credential's scope",
      "received": "1000000009",
      "allowed": ["1000000001", "1000000002"]
    }
  ]
}

The message is unchanged from earlier releases, so integrations reading only that key are unaffected.

A request that names no billing provider returns the same message without an errors array: there is no submitted value to report back.

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"
    }
  ]
}

Provisioning prerequisites

A 422 can also mean the request is well formed but your organization is not set up for it yet, most often a resource that depends on a billing provider, created before one exists. errors[] names the field and the setup step.

{
  "message": "Provisioning prerequisites are not met; complete the listed setup steps and retry",
  "errors": [
    {
      "field": "contracting_provider_id",
      "message": "This organization has no billing provider. Create one with POST /api/organization-providers/v3 and is_billing: true before creating a contract."
    }
  ]
}

The full sequence is in the provisioning order.

Status codes

StatusClassMeaning
400ClientMalformed request, unsupported organization override, or missing fields
401AuthBearer token is missing, malformed, or expired
403AuthCredential or organization is not allowed to perform the request
404ClientRoute or resource is not available to the credential
409ClientRequest conflicts with current resource state
422ValidationOne or more request fields failed validation
429Rate limitThe credential is being rate limited
500ServerUnexpected Taiga error
502IntegrationTaiga could not safely complete the upstream billing operation

Retry guidance

1

Retry only transient failures

429, 500, 502, network timeouts.

2

Use exponential backoff

Start small (250–500 ms) and double up to a cap (e.g. 30 s).

3

Cap the retry count

Surface the original error after the cap so callers can react.

4

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.