Errors and limits

This page lists what the REST API answers when something is wrong, in the order the checks run, and every limit that applies to keys and requests. Use it to decide which errors to retry and which to fix.

Error shape

Every error is JSON with a human-readable message:

{
  "message": "Invalid API key."
}

Validation errors add an errors object. Each key is a field name and each value is a list of messages:

{
  "message": "The Name field is required.",
  "errors": {
    "name": ["The Name field is required."]
  }
}

Messages are in English and may change wording. Decide what to do from the status code and the keys of errors, not from the message text.

Order of checks

Each request is checked in this order, and the first failure answers:

1. The per-address limit of 600 requests a minute for the endpoint. Over it gets 429 Too Many Attempts.
2. HTTPS. Plain HTTP gets 403 HTTPS is required.
3. The key. A missing, wrong or revoked key, or one whose creator or company is no longer active, gets 401 Invalid API key.
4. The plan and the creator's custom role. Without API access the answer is 403 API access is not in this plan.
5. For POST and DELETE: a Read only key gets 403 This key is read only.
6. For POST and DELETE: a body that is not declared as JSON gets 415 Send JSON.
7. The key's limit of 120 requests a minute. Over it gets 429 Too many requests.
8. The endpoint itself: role, validation and records.

Status codes

Retrying safely

Retry only 429 and 500, and errors where no response arrived. Wait before each retry and make the wait longer each time. Remember that creating a deal or adding a note twice creates two records, so check before you retry those. See Idempotency.

Limits

Your plan may also limit how many contacts the company can hold. When that limit is reached, creating a contact answers 422 with the error under limit.

Troubleshooting