Developers

Limits and errors

Rate limits

LimitDefaultHow it works
Per key60 requests a minuteA bucket that refills steadily, so short bursts are fine.
Per account10,000 requests a dayShared 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 429 and nothing runs.
  • Only a 200 with a result is charged. A run that answers no_data, needs_review or invalid, or any error, costs nothing.
  • Send an Idempotency-Key header 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 503 with no result, and the message says whether a retry is safe. Retry with the same Idempotency-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.

StatusCodeWhen
401—The key is missing, mistyped, revoked or rotated, or its teammate is archived.
403api_access_offThe 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.
403not_allowedThe path, or the op inside the body, isn't open to API keys.
403scopeThe key lacks a scope the endpoint needs. The needs array lists them.
403rep_accessThe endpoint lists records across the whole account, and the key's teammate can only see some of them.
429rate_limitedThis key made too many requests in the last minute.
429rate_limitedThe account used all of its API requests for the day (UTC).
429wallet_exhaustedAn analysis run needs an AI credit and the account's balance is used up. Nothing ran and nothing was charged.
429seat_capAn 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.
402plan_requiredUnderwrite a property needs the Scale or Pro plan. Nothing ran and nothing was charged.
409idempotency_conflictThe idempotency key was already used for a different underwrite: another lead, address or facts.
503underwrite_offUnderwriting is off for this workspace, or isn't live yet. Nothing ran and nothing was charged.
503charge_unknownAn 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.
429queue_full200 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"
}
Limits and errors | Syntropic Developers