> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taigabilling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taigabilling.com/_mcp/server.

# Errors

The Partner API returns standard HTTP status codes and JSON error responses.

## Error envelope

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](/tenant-scoping#provisioning-order).

## 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.