---
url: /api/errors.md
description: >-
  RFC 9457 problem+json error envelope, common HTTP statuses, and example error
  bodies.
---

# Errors

All API errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` responses.

***

## Error envelope

```json
{
  "type": "https://telegramtometatrader.com/problems/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Unknown trade status 'foo'."
}
```

| Field | Type | Description |
|:---|:---|:---|
| `type` | `string` | A stable URI identifying the error type. Branch on this in code — never on `detail`. |
| `title` | `string` | Short human-readable label for the error type. |
| `status` | `integer` | HTTP status code, mirrored in the body for convenience. |
| `detail` | `string` | Optional. Specific message for this occurrence. |

***

## Status codes

| Code | Meaning |
|:---|:---|
| `200` | OK |
| `304` | Not Modified (terminal trade/signal with matching `If-None-Match`) |
| `400` | Bad request — invalid or missing parameter |
| `401` | Authentication failed — missing, malformed, unknown, or revoked key |
| `403` | API access disabled for the account |
| `404` | Resource not found, or belongs to a different user |
| `405` | Method not allowed — the surface is GET-only |
| `409` | Conflict — a concurrent stream is already open for this key |
| `429` | Rate limit exceeded |
| `503` | Live container unavailable (stream only) |

***

## Example responses

**Missing authentication:**

```json
{
  "type": "https://telegramtometatrader.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization header is required."
}
```

**API access disabled:**

```json
{
  "type": "https://telegramtometatrader.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "API access is not enabled for this account."
}
```

**Invalid parameter:**

```json
{
  "type": "https://telegramtometatrader.com/problems/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Unknown trade status 'foo'."
}
```

**Not found:**

```json
{
  "type": "https://telegramtometatrader.com/problems/not-found",
  "title": "Not Found",
  "status": 404
}
```

**Rate limited:**

```json
{
  "type": "https://telegramtometatrader.com/problems/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 12 seconds."
}
```

**Concurrent stream conflict:**

```json
{
  "type": "https://telegramtometatrader.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A stream is already open for this API key."
}
```

***

## Handling errors in code

Branch on `type` (stable), not on `detail` (prose, may change):

```python
resp = requests.get(f"{BASE}/trades", headers=headers)
if not resp.ok:
    err = resp.json()
    if err["type"].endswith("/unauthorized"):
        raise AuthError("check your API key")
    elif err["type"].endswith("/rate-limited"):
        time.sleep(int(resp.headers.get("Retry-After", 60)))
    else:
        raise ApiError(err["detail"])
```

## Related pages

* [Authentication](/api/authentication) — API key format, lifecycle, and header requirements
* [Rate Limiting](/api/rate-limiting) — request limits, backoff strategy, and `Retry-After` headers
* [API Quickstart](/api/quickstart) — getting started with REST endpoints and streaming
