> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting hub

> Start here when a Tirdad integration misbehaves: the symptom-to-cause table, the diagnostic tools, and where each deep-dive lives

Most integration problems fall into a handful of shapes, and each has a fast check. Find your symptom below, run the check, and follow the link for the full write-up.

## What symptom are you seeing?

| Symptom | Most likely cause | Check |
| - | - | - |
| `401 Unauthorized` on every request | Missing or expired key | Run the auth check below |
| `403 Forbidden` on some requests | The key's role lacks the permission | [API key roles](https://docs.tirdad.ai/docs/rbac/manage-api.md#getting-403-forbidden-errors) |
| `404` on every request | Base URL is missing `/v1` or has a trailing slash | Compare against `https://api.tirdad.ai/v1` |
| `404` on one object | Wrong ID, or the object lives in another environment | Keys are bound to one environment; sandbox IDs are invisible to a production key |
| `400` with a validation message | A required field is missing or an enum value is wrong | Read `error.message`; it names the field. [Error responses](https://docs.tirdad.ai/api-reference/error-responses.md) |
| `409 Conflict` | Two writes raced, or the object already exists | Retry the read, or look the object up. Safe to retry |
| `429 Too Many Requests` | Rate limit | Back off with jitter; batch events with `POST /events/bulk` |
| Event returns `202` but never shows up | `event_name` does not match a feature exactly, or `external_customer_id` matches no customer | [Usage events not showing up](https://docs.tirdad.ai/docs/event-ingestion/troubleshooting.md#1-events-not-appearing-in-dashboard), and subscribe to `event.rejected` |
| Usage number is wrong | Aggregation field name or type mismatch | [Wrong aggregation values](https://docs.tirdad.ai/docs/event-ingestion/troubleshooting.md#2-wrong-aggregation-values) |
| Usage shows but the invoice has no charge | Feature is not priced in the plan, or the customer has no subscription | [No charges in billing](https://docs.tirdad.ai/docs/event-ingestion/troubleshooting.md#3-no-charges-in-billing) |
| Webhook never arrives | Endpoint not subscribed to that event, or registered in the other environment | Dashboard **Webhooks > Logs**; [Set up an endpoint](https://docs.tirdad.ai/developers/webhooks/set-up-an-endpoint.md) |
| Webhook arrives, signature check fails | Handler verifies a re-serialized body instead of the raw bytes | [Signature verification](https://docs.tirdad.ai/developers/webhooks/signature-verification.md) |
| Webhook delivered more than once | At-least-once delivery | Dedupe on `svix-id`; [Retries and ordering](https://docs.tirdad.ai/developers/webhooks/retries-and-ordering.md) |
| MCP server does not appear | Config not saved, or the client was not restarted | [MCP troubleshooting](https://docs.tirdad.ai/docs/connect/mcp-server.md#troubleshooting-the-mcp-server) |

The auth check, with your key in `$KEY`:

```sh theme={null}
curl -s -X POST "https://api.tirdad.ai/v1/customers/search" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{}'
```

A `200` with an `items` array means the key works.

## Tools that show what happened

> [card] [Event Debugger](https://docs.tirdad.ai/docs/event-ingestion/event-debugger.md)
>
> Every ingested event with how it matched a feature and aggregated. The first stop for any metering question.

> [card] [Webhook logs](https://docs.tirdad.ai/developers/webhooks/set-up-an-endpoint.md#watching-webhook-deliveries-in-the-dashboard)
>
> Each delivery attempt, the response your endpoint returned, and a replay button.

> [card] [Ingestion monitoring](https://docs.tirdad.ai/docs/event-ingestion/monitoring.md)
>
> Throughput and rejection counts over time, to tell a code bug from a traffic change.

## Deeper troubleshooting guides

* [Usage events troubleshooting](https://docs.tirdad.ai/docs/event-ingestion/troubleshooting.md): the long version of every metering problem
* [Validating events](https://docs.tirdad.ai/docs/event-ingestion/validating-events.md): what the ingest endpoint checks and what it does not
* [Error responses](https://docs.tirdad.ai/api-reference/error-responses.md): every status code and the error body shape
* [API key troubleshooting](https://docs.tirdad.ai/docs/rbac/manage-api.md#troubleshooting): keys that stopped working, lost keys, and role errors
* [MCP server troubleshooting](https://docs.tirdad.ai/docs/connect/mcp-server.md#troubleshooting-the-mcp-server): connection, login, region, and URL problems

## Still stuck?

Bring the request ID or the `svix-id`, the environment, the region, and the exact time to [support@tirdad.ai](mailto:support@tirdad.ai).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.