Errors and limits

The envelopes

A successful response has a data member (the operation’s object, or an array for a search) and a meta member with the request ID, paging fields (limit, total, next_cursor, and total_relation: lower_bound when a total is a minimum), warnings and the sources behind the answer, each with its own date. An error has an error member with a code, a message written for a person and bounded details for your code, plus the same meta:

1{2  "error": {3    "code": "rate_limit_exceeded",4    "message": "The Free plan allows 30 requests a minute.",5    "details": { "bucket": "free_per_minute" }6  },7  "meta": { "request_id": "req_3f9a1c7e5b2d4a6f8c0e1b3d7a9c2e4f" }8}

Optional fields are left out when empty. A few fields return null for unknown, as their descriptions say. Empty results describe the current page and filters. Read meta.warnings for the search scope and check next_cursor for more pages.

HTTP status

Error codes

Limits

The plans set the allowances and say what counts as a request. A CODE-RESOLVE or INVENTORY-CHECK batch of up to 100 items counts as one request. Additional request limits also apply; a 429 identifies the exceeded limit in details.bucket:

API Playground requests count like any other, and the playground sends at most 20 a minute per network.

Rate-limit headers

A counted response, success or error, carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until reset) for the allowance window with the least remaining. A request refused before the key is known (401, 403) carries none, and neither does a replayed idempotent response. On a 429 the headers describe the limit that was exceeded and RateLimit-Reset equals Retry-After; the in-flight limit sends RateLimit-Limit, RateLimit-Remaining (0) and Retry-After, with no RateLimit-Reset.

Retries and the idempotency key

Every operation is read-only, so a retry is safe. To keep a retry from counting twice, send an Idempotency-Key header of 8 to 128 characters (letters, digits and . _ : / + -, starting with a letter or digit). For 24 hours the key is bound to your workspace and the exact method, target and body; a retry with the same key reruns the request and is not counted again when its response matches the first. Reusing a key for different work is refused. If the response changed, the retry answers 409 idempotency_response_changed. A key allows about 10 attempts in total, retries included; after that the API answers 409 idempotency_replay_limit and the client should use a new key.

Request ceilings

• 10,000 rows read from the database per request, including rows read to build the answer (query_timeout, 503). Lower limit or add a filter.
• 8 MiB per response (response_too_large, 413). Lower limit, drop an include, or page.
• Per-operation batch sizes, for example 100 codes in CODE-RESOLVE (batch_too_large, 413).
• 256 KiB of strings in one request, 20 levels of nesting, 200 fields per object and 500 items per list (request_too_complex, 413).

Versioning and changes

Every path starts with /v1, and each successful response carries an X-API-Version header. X-Data-As-Of dates the data behind a response (the oldest data_as_of among its sources) and X-Data-Snapshot identifies its release; the API version is the one in the path.

These changes are breaking, and we email at least 90 days’ notice before making one, except as section 8 of the Terms allows:

• Removing or renaming an operation, field or enum value
• Changing a field’s type or meaning
• Newly requiring a parameter

These are not breaking, and take effect when they appear in these docs:

• Adding operations
• Adding optional parameters
• Adding response fields or enum values

Section 8 of the Terms of Service sets the notice periods.