Errors and limits

Error format

Errors are returned as application/problem+json:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "a column name is required"
}

detail is written for a person to read and is safe to show to your users. Don't parse it, because the wording may change. Branch on status.

When something goes wrong on our side, detail includes a reference:

{
  "status": 500,
  "title": "Internal Server Error",
  "detail": "The request could not be completed. Quote reference 3fa91c07d2b4 if you report this."
}

Send that reference to [email protected] and we can find exactly what happened.

Status codes

Code	Meaning	What to do
200 / 201	Success / created.
204	Success, no body.
400	The request is malformed or a value is invalid. detail says which.	Fix the request. Don't retry it unchanged.
401	No credentials, or the API key is invalid or revoked.	Check the Authorization header and the key.
402	Your subscription doesn't allow this: it has lapsed (the account is read-only), you've reached your plan's reader limit, or the feature is an add-on you don't have.	See Subscription. Retrying won't help.
403	Your role doesn't allow it (API keys can't manage users, keys, the audit log or billing), or the account is suspended.
404	That thing doesn't exist on your account.
409	Conflicts with the current state. For example, checking out an asset that's already checked out, or renaming a column to a name that's taken.	Re-read the current state, then decide.
429	Too many requests.	Wait for the number of seconds in the Retry-After header.
500 / 502 / 503	A problem on our side.	Retry with backoff. If it persists, contact support with the reference.

Rate limits

Limit	Allowance
Per API key	2,000 requests per minute
Per source IP address (all users and keys combined)	1,000 requests per minute

Both apply. If you have several integrations behind one office IP address, they share that address's allowance. Over the limit, you get 429 with Retry-After: 60.

Failed authentication is limited separately. After 30 requests with invalid keys from one IP address within 15 minutes, that address is locked out for 15 minutes (429, Retry-After: 900). This most often happens to a job still running with a revoked key, so update the key rather than retrying.

To stay well inside the limits:

• Use bulk endpoints. One CSV import replaces thousands of single-tag writes.
• Use the live event stream instead of polling for changes.
• Back off on 429 and 5xx responses.

Size limits

What	Limit
JSON request body	1 MB
CSV import file	64 MB and 100,000 rows
Tags per bulk delete	10,000
Request duration	60 seconds (the event stream is exempt)

Read-only and suspended accounts

When a subscription lapses, GET requests keep working and every write returns 402 with a detail explaining why. When an account is suspended or closed, every request returns 403. See Subscription.