---
title: "Errors"
url: "https://trialvalid.com/docs/errors.md"
canonical_url: "https://trialvalid.com/docs/errors"
last_updated: "2026-10-19"
type: "reference"
summary: "The error envelope the service uses, its fields, and the codes a seller can see."
related: ["https://trialvalid.com/docs/api.md", "https://trialvalid.com/docs/webhooks.md"]
---

# Errors

> **For AI agents:** the complete index of TrialValid pages is [llms.txt](https://trialvalid.com/llms.txt). Every page is also served as markdown at its URL plus .md.

The error envelope the service uses, its fields, and the codes a seller can see.

> Every error from the service and the API uses this envelope.

## Envelope

```json
{
  "error": {
    "code": "conflict",
    "message": "The resource is in a state that does not allow this action.",
    "fix": "Read the resource and check its state.",
    "docs_url": "https://trialvalid.com/docs/errors#conflict",
    "retryable": false,
    "request_id": "req_example"
  }
}
```

Branch on `code`. `fix` says what to change, and `retryable` says whether sending the same request again can work.

## Codes

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| `unauthorized` | 401 | No | The API key is missing, malformed, revoked or unknown |
| `forbidden` | 403 | No | This key is not allowed to make this request |
| `invalid_input` | 400 | No | The request input is invalid |
| `not_found` | 404 | No | No such resource exists for this account |
| `conflict` | 409 | No | The resource is in a state that does not allow this action |
| `signature_invalid` | 400 | No | A webhook signature or connect state did not verify |
| `rate_limited` | 429 | Yes | Too many requests for this key. Wait for `Retry-After` |
| `provider_unavailable` | 503 | Depends | A vendor is unavailable or not configured. If `retryable` is false, retrying will not help |
| `internal_error` | 500 | Once | Retry once with backoff |

Another account's resource looks exactly like a missing one, so `not_found` never reveals that a resource exists.

## Related

- [API overview](https://trialvalid.com/docs/api.md)
- [Webhooks](https://trialvalid.com/docs/webhooks.md)