# Requests, errors and limits

> The conventions every API call follows, including JSON, times and dates, pagination, errors, plan limits and the rate limit.

## Format

- JSON in, JSON out. Send `Content-Type: application/json` with a body.
- Dates are ISO 8601 strings, like `2026-10-02T15:00:00Z`. Date-only fields use `YYYY-MM-DD`.
- Text is trimmed and cut to the field's length rather than refused.
- An unknown choice, like an intent or a task kind we don't have, is ignored rather than refused.
- In a `PATCH`, a field you leave out is left alone, and `null` clears it.
- Custom field values arrive as text (numbers and true/false are converted), at most 50 per request.

## Times and time zones

- **A time without a zone** is read on the clock of the person behind the credential. `2026-10-14T17:00` is 5 PM where they are.
- **A date alone, where a time is expected,** is 10 AM that day on their clock.
- **A `from` or `to` that's a date alone** covers that whole day.
- **Days, like a deal's contract and closing dates,** are sent as that day's UTC midnight. Read them as a date, not a moment.

## Pagination

Lists that can grow long page by cursor. Pass `limit`, then pass the answer's `nextCursor` as `cursor` to get the next page. A `null` `nextCursor` means you've reached the end.

```bash
curl "https://workspace.brokerandagent.com/api/public/v1/contacts?limit=25&cursor=ct_…" \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

- **Paged by cursor:** `/contacts`, `/inbox/threads`, `/documents`, `/smart-lists/{id}/members`, `/tasks`, `/appointments` and `/envelopes`.
- **Paged only when you pass `limit`:** `/transactions` and `/tours`. Without `limit` they answer with everything.
- **Page sizes differ.** The default is 25 for contacts, 50 for threads and 200 for tasks.
- A `limit` above the call's maximum is treated as that maximum, and one below 1 as 1.

A cursor for a record that has since been deleted answers `422`; start again from the first page.

## Errors

Every error has the same shape:

```json
{ "error": { "code": "validation", "message": "email: Not a valid email address" } }
```

Branch on `code`, never on the wording of `message`, which can change.

| Status | Code | Meaning |
|---|---|---|
| `400` | `bad_json` | The body isn't a JSON object |
| `400` | `bad_idempotency_key` | The `Idempotency-Key` is malformed. See [Retrying safely](https://brokerandagent.com/developers/api/idempotency) |
| `401` | `unauthorized`, `workspace_suspended` | See [Authentication](https://brokerandagent.com/developers/api/authentication#errors) |
| `402` | `upgrade_required` | The workspace's plan doesn't include this, or the workspace is at a plan limit. The reason is in `message` |
| `403` | `insufficient_scope`, `insufficient_access`, `forbidden`, `workspace_not_granted`, `wrong_audience`, `ip_not_allowed`, `ai_apps_off`, `awaiting_approval` | The credential can't do this, or can't reach this record or workspace. See [Authentication](https://brokerandagent.com/developers/api/authentication#errors) |
| `404` | `not_found` | No such record, or none the credential can see |
| `409` | `idempotency_in_progress` | A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` |
| `409` | `flow_off` | The automation you tried to start is switched off |
| `409` | `in_progress` | A copy of the same request is still being handled |
| `422` | `validation` | A field is the wrong kind; the message names it |
| `422` | `idempotency_key_reused` | The same `Idempotency-Key` came with a different body or path |
| `429` | `rate_limited` | Too many requests; see below |
| `500` | `internal` | Something went wrong on our side |
| `503` | `unavailable` | Briefly unavailable. Retry shortly |

## Rate limits

Each key or connection can make **120 requests a minute**, and each IP address gets 10 tries a minute with a bad credential. Over either, calls answer `429 rate_limited` with a `Retry-After: 60` header. Wait, then retry. Spreading requests out works better than bursts.

There are no `RateLimit-*` headers yet, and the count is approximate, since it's kept per Cloudflare location.

## Plan limits

The API is on every Workspace plan, Free included. A workspace at a plan limit answers `402 upgrade_required`, with the reason in `message`.

Today one call can meet a limit: `POST /contacts`, when a Free workspace already holds its 100,000 contacts, plus 25,000 for each extra login. Leads always land: lead-capture keys, `POST /events` and `POST /site-leads` are never refused for a limit.

Some answers follow the workspace's add-ons rather than refusing. Without the collaboration add-on, `GET /reports` covers the credential's own person, and calendar `attendees` are left off a booking.

## Answers that wait for a person

A connected app (OAuth) can be set to ask its person first. Then starting an automation or removing a tour stop answers `202` with a `proposal`, and nothing runs until the person approves it in the app. API keys never ask first. See [Build an app with OAuth](https://brokerandagent.com/developers/oauth#ask-before-sending-or-deleting).

## Build for change

Within `v1` the API only grows: new calls, new fields, new values. Ignore fields and values you don't recognize, and your integration keeps working. See [Versioning and changes](https://brokerandagent.com/developers/api/versioning).

---

Source: https://brokerandagent.com/developers/api/requests
