API rules

These rules apply to every operation of the API. On this page:

• Errors: The error format, the list of codes and what to do in each case.
• Limits: How many requests you can make, how to see how many are left and what to do when you exceed the limit.
• Pagination: How list operations split results into pages.
• Retries (Idempotency-Key): How to repeat a request safely, without doing the same thing twice.
• Sandbox and Production: The two API modes: what sandbox_ and prod_ keys do, and how to confirm the mode on each request.

Errors

Format

Every error has the same shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Codes

Retry or not

• Worth retrying, after a wait: 429, 500, 502 and 503.
• Not worth retrying without changing something: all the others.

On a POST request, always send Idempotency-Key from the first attempt and retry with the same value.

Report a problem

Give support the correlation_id, the time of the request and the operation. Never send the key: support does not need it.

Limits

Request limits

These are the current values and they can change. In your programs, read the headers instead of hard-coding the numbers. GET /v1/ping and GET /v1/openapi.json always count per IP, even with a key.

Headers

Responses include:

The GET /v1/limits operation shows the same values, plus the key's spending limit.

When you exceed the limit

The API answers 429 with the code rate_limited and the Retry-After header, which says how many seconds to wait.

• Wait at least that long before retrying.
• If the 429 comes back, wait longer on each attempt.
• Avoid very fast polling loops.

Request size

A request body can have up to 1048576 bytes (1 MB).

Pagination

Parameters

An example of what is added to the address:

?page=2&per_page=50

Response

The results come in data, and meta says where you are:

{
  "data": [],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 120,
    "total_pages": 3
  }
}

Read all pages

Start at page=1 and continue while page is lower than total_pages. Each page counts as one request towards the limits.

Retries (Idempotency-Key)

What it is for

If the connection fails halfway through a request, you do not know whether it went through. With the Idempotency-Key header, you can repeat the request with no risk of registering or charging twice.

How to use it

Generate a unique value for each operation and send it on a POST request:

Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e

The value can have up to 255 visible characters. A UUID works well. Repeat the same value only when you repeat the same operation.

What happens

The value stays reserved for each key for 24 hours.

After a failure

• If you got no response: repeat the request with the same value.
• If you got 409 because the first is still in progress: wait a little and repeat.
• If you got 409 because the body is different: use a new value, if it really is a different operation.

Sandbox and Production

Two modes

The address is the same in both modes: the key decides.

What the response says

• Every response to a request with a key has the X-API-Mode header, with sandbox or production.
• Simulated writes also have X-API-Simulated: true.
• While the API is in preparation, not even prod_ keys change the account or charge: writes are simulated and the writes_simulated field of GET /v1/token is true.
• Keys created during the preparation, in either mode, are revoked when the API opens, and the account owner gets a notice by email. After that, create new keys.

Find out the mode of a key

The mode field of GET /v1/token says sandbox or production.

To make sure a program never runs with the wrong key, send the X-API-Mode header on the request. If it does not match the mode of the key, the API refuses with invalid_request and the reason mode_mismatch.

Playground

Each operation, on the page of its area, has the Playground button, to make requests from the browser without leaving the page.

• The key you type stays only in the memory of that page: it is not saved and never goes in the URL.
• Use a sandbox_ key. prod_ keys act on your account.

Going to Production

When the program is ready, create a prod_ key with the minimum permissions, on the API page. The prefix is the only difference in the request.