Limits and errors
Rate limits
| Limit | Default | How it works |
|---|---|---|
| Per key | 60 requests a minute | A bucket that refills steadily, so short bursts are fine. |
| Per account | 10,000 requests a day | Shared by all of the account's keys. Resets at midnight UTC. |
- Every request with a working key counts, including refused ones and ones held for approval.
- Over MCP, each tool call counts once, the same as the REST request it makes. Connecting and listing tools don't count toward either limit. They have their own flood guard of 600 requests a minute per key, and going over it gets the same 429.
- Need more? Email support@syntropic-crm.com.
A request over a limit gets 429 with a Retry-After header in seconds. Wait that long before retrying.
AI credits
The analysis endpoints (underwriting, Deal Analyzer, stress test, rehab estimate and creative finance) cost 1 AI credit per successful run, from the account's AI credits balance. Underwrite a property costs 100, charged only when it finishes ok. Getting a run is free. Other endpoints don't use AI credits.
For the five analysis endpoints:
- The balance is checked before the run. If it's used up, or the teammate has reached their monthly cap, the answer is
429and nothing runs. - Only a
200with a result is charged. A run that answersno_data,needs_revieworinvalid, or any error, costs nothing. - Send an
Idempotency-Keyheader with a value unique to each run, up to 200 characters. A retry with the same key and body is never charged twice, and returns the paid result. - If the charge can't be confirmed, the answer is
503with no result, and the message says whether a retry is safe. Retry with the sameIdempotency-Key. - Over MCP, analysis tools cost the same. Each tool call is its own run.
Underwrite a property answers at once with a run id, not a result. The balance is checked when the run starts work: if it's used up, the run ends with status error and nothing is charged. Poll comps-underwrite.get for the outcome. A retry with the same Idempotency-Key and body returns the same run, so it is never charged twice.
Errors
Errors are JSON with an error message you can show a person. Refusals that are about the key also carry a code to branch on. Nothing is changed when a request is refused.
| Status | Code | When |
|---|---|---|
| 401 | — | The key is missing, mistyped, revoked or rotated, or its teammate is archived. |
| 403 | api_access_off | The key is valid, but API access is switched off for its account. REST and MCP both answer this way. |
| 400 | — | The body isn't JSON, or a required field is missing or out of range. |
| 403 | not_allowed | The path, or the op inside the body, isn't open to API keys. |
| 403 | scope | The key lacks a scope the endpoint needs. The needs array lists them. |
| 403 | rep_access | The endpoint lists records across the whole account, and the key's teammate can only see some of them. |
| 429 | rate_limited | This key made too many requests in the last minute. |
| 429 | rate_limited | The account used all of its API requests for the day (UTC). |
| 429 | wallet_exhausted | An analysis run needs an AI credit and the account's balance is used up. Nothing ran and nothing was charged. |
| 429 | seat_cap | An analysis run needs an AI credit and the key's teammate has reached their monthly AI credits cap. |
| 400 | — | A comps-underwrite run got both leadId and address, or neither. |
| 402 | plan_required | Underwrite a property needs the Scale or Pro plan. Nothing ran and nothing was charged. |
| 409 | idempotency_conflict | The idempotency key was already used for a different underwrite: another lead, address or facts. |
| 503 | underwrite_off | Underwriting is off for this workspace, or isn't live yet. Nothing ran and nothing was charged. |
| 503 | charge_unknown | An analysis run's AI credits charge couldn't be confirmed, so no result was returned (see AI credits). |
| 404 | — | The record doesn't exist, or the key's teammate can't see it. The two look the same on purpose. |
| 429 | queue_full | 200 actions already wait for approval on the account (see Needs approval). |
| 409 | — | The change clashes with the record, such as a duplicate phone or email. The endpoint says how to go ahead. |
401
The key is missing, mistyped, revoked or rotated, or its teammate is archived. Check the Authorization header. In Settings › API and agents, rotate or make a new key.
{
"error": "Invalid or revoked agent token."
}403 api_access_off
The key is valid, but API access is switched off for its account. REST and MCP both answer this way. A new key won't help: API access has to be back on for the account. If Settings › API and agents isn't there for the owner, email support@syntropic-crm.com.
{
"error": "API access is turned off for this account. An owner can turn it on in Settings › API and agents.",
"code": "api_access_off"
}400
The body isn't JSON, or a required field is missing or out of range. Fix the request using the endpoint's fields below.
{
"error": "leadId is required."
}403 not_allowed
The path, or the op inside the body, isn't open to API keys. Use only the endpoints in the reference. Anything not listed refuses keys.
{
"error": "op \"archive\" on this endpoint isn't available to API keys.",
"code": "not_allowed"
}403 scope
The key lacks a scope the endpoint needs. The needs array lists them. Edit the key's scopes in Settings › API and agents, or use a key that has them.
{
"error": "This key needs leads:write.",
"code": "scope",
"needs": [
{
"area": "leads",
"level": "write"
}
]
}403 rep_access
The endpoint lists records across the whole account, and the key's teammate can only see some of them. Use a per-record endpoint, or a key for a teammate who sees the whole book.
{
"error": "This list covers leads across the whole account, and this key's teammate can only see some of them. Use lead get or find instead.",
"code": "rep_access"
}429 rate_limited (key_minute)
This key made too many requests in the last minute. Wait the number of seconds in Retry-After, then retry. Spread requests out.
Header: Retry-After: 12
{
"error": "This key is sending requests too fast.",
"code": "rate_limited",
"limit": "key_minute"
}429 rate_limited (account_day)
The account used all of its API requests for the day (UTC). Retry after midnight UTC, when Retry-After runs out.
Header: Retry-After: 3600
{
"error": "This account has used its daily API requests.",
"code": "rate_limited",
"limit": "account_day"
}429 wallet_exhausted
An analysis run needs an AI credit and the account's balance is used up. Nothing ran and nothing was charged. Add AI credits in Settings › Billing, or wait for the monthly allotment.
{
"error": "This API key is paused: this account's AI credits are used up. Add AI credits in Settings → Billing, or wait for the monthly allowance to refill.",
"reason": "wallet_exhausted"
}429 seat_cap
An analysis run needs an AI credit and the key's teammate has reached their monthly AI credits cap. An admin can raise the cap in Settings › Team, or wait for the billing period to roll.
{
"error": "This API key is paused: this seat has reached its monthly AI credits limit. An admin can raise it in Settings → Team, or it resets when the billing period rolls.",
"reason": "seat_cap"
}400
A comps-underwrite run got both leadId and address, or neither. Send exactly one of leadId or address.
{
"error": "Give exactly one of leadId or address."
}402 plan_required
Underwrite a property needs the Scale or Pro plan. Nothing ran and nothing was charged. Upgrade from the billing portal.
{
"error": "Underwriting comes with the Scale and Pro plans. Upgrade from the billing portal to use it.",
"code": "plan_required"
}409 idempotency_conflict
The idempotency key was already used for a different underwrite: another lead, address or facts. Use a new idempotency key for each different request.
{
"error": "This idempotency key belongs to a different underwriting request.",
"code": "idempotency_conflict"
}503 underwrite_off
Underwriting is off for this workspace, or isn't live yet. Nothing ran and nothing was charged. Try again later, or ask an admin to turn underwriting on.
{
"error": "Underwriting isn't live yet.",
"code": "underwrite_off"
}