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

# Errors & Limits

> The BrikSync PropOS API error format, every error code and what to do about it, and how rate limits and daily request allowances work.

## Error format

Every failure across the API and the AI assistant endpoint uses the same shape:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"leases:propose\" scope.",
    "requestId": "..."
  }
}
```

| Field | Description |
| - | - |
| `code` | A stable, machine-readable string. Branch your integration's logic on this, not on `message`. |
| `message` | A human-readable explanation, safe to log or show to whoever's debugging the integration. |
| `detail` | Present only on some validation failures — an array of `{ field, message }` pairs pointing at exactly which part of the request was wrong. |
| `requestId` | A correlation ID for this specific request. Include it if you contact us about a specific failure. |

***

## Error codes

| Code | HTTP status | Meaning | What to do |
| - | - | - | - |
| `unauthenticated` | 401 | No API key was sent, or the `Authorization` header is malformed. | Send `Authorization: Bearer <key>` on every request. |
| `invalid_credentials` | 401 | The key doesn't match any active key. | Check the key value. If it's genuinely lost, revoke it and create a new one. |
| `credential_revoked` | 401 | This key has been revoked. | Create a new key — a revoked key cannot be restored. |
| `credential_expired` | 401 | This key has passed its expiry date. | Create a new key. |
| `insufficient_scope` | 403 | The key doesn't hold a scope this request needs. | Add the missing scope to the key, or create a new key with it. |
| `forbidden` | 403 | The key's access level doesn't permit this operation. | Use a key issued at a higher access level, or ask an Admin to do so. |
| `plan_required` | 403 | Your organisation isn't on the Business plan. | Upgrade from **Settings → Billing**. |
| `not_found` | 404 | No such record — either it doesn't exist, or it belongs to another organisation. | Double-check the ID and collection name. |
| `invalid_request` | 400 | The request couldn't be processed as sent — a bad parameter, an invalid cursor, or a body that failed validation. | Check `detail` (if present) for which field, and the relevant page in this API section for the expected shape. |
| `unsupported_version` | 400 | The requested API version doesn't exist. | Use `/api/v1`. |
| `idempotency_conflict` | 409 | You reused an `Idempotency-Key` with a different request body than the first time. | Use a new, unique key for a genuinely new request. See [Suggesting Changes](https://docs.briksync.com/api/suggesting-changes.md). |
| `rate_limited` | 429 | You've sent too many requests too quickly. | Slow down and retry after the interval in the `Retry-After` header. |
| `quota_exceeded` | 429 | This key has used its daily request allowance. | Wait until the allowance resets, or spread requests across more of the day. |
| `server_error` | 500 | Something went wrong on our side. | Retry with backoff. If it persists, contact us with the `requestId`. |

> [!NOTE]
>
> A record that doesn't exist and a record that belongs to a different organisation both return the
> identical `not_found` — this is intentional, so a caller can never use the difference between
> responses to learn whether a record exists somewhere it shouldn't be able to see.

***

## Rate limits

Requests are limited **per API key**, so one busy integration can't slow down another key on your own account, and traffic from other BrikSync customers never affects your key either way.

| Limit | Allowance |
| - | - |
| Per-minute rate limit | 100 requests per minute, per API key |
| Daily request allowance | 10,000 requests per day, per API key |

Exceeding the per-minute limit returns `rate_limited` (429) with a `Retry-After` header telling you how many seconds to wait before trying again. Exceeding the daily allowance returns `quota_exceeded` (429), also with a `Retry-After` header, and resets at the start of the next day (UTC).

> [!TIP]
>
> Both limits are generous enough that a normal integration should never come close to them. If
> you're hitting them regularly, it usually means a retry loop is running faster than it should —
> check that failed requests back off instead of retrying immediately.

```bash theme={null}
# A 429 response includes Retry-After, in seconds
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry after the interval in the Retry-After header.",
    "requestId": "..."
  }
}
```

***

## Page size limits

List endpoints cap `limit` at **100** records per page (default 25) — see [Reading Data](https://docs.briksync.com/api/reading-data.md) for full pagination details. Asking for more than 100 returns `invalid_request`, not a silently truncated response.

***

## Getting help

If you hit an error you can't resolve, contact us through the contact form and include the `requestId` from the failed response — it lets us find the exact request without you needing to share your API key or any of your data.


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