Errors and rate limits

Envelopes

Successful responses wrap their payload in data:

{ "data": { "packageId": "pkg_9f3c2e" } }

Errors carry a human-readable error and, for validation failures, a details map:

{
  "error": "Validation failed",
  "details": {
    "recipients.0.email": ["Invalid email"],
    "title": ["Required"]
  }
}

Creates return 201; everything else that succeeds returns 200.

Status codes

Status	When
`400`	The body is not valid JSON (`Invalid JSON body`), or the action is not possible in the package’s current state (for example `Only DRAFT packages can be sent`, or a transfer to a user outside the organisation).
`401`	Missing, malformed, unknown, revoked or expired API key. See Authentication.
`402`	The plan does not include the feature (public API, webhooks), the organisation has no credit left to send, or a plan limit such as recipients per package or number of templates would be exceeded. The message says which.
`403`	The caller’s IP address is outside the organisation’s allowlist, the key’s user lacks a permission (`Missing permission: canSendPackages`), or the endpoint needs an organisation admin.
`404`	The package, template or webhook endpoint does not exist in the workspace or organisation the call acted in.
`422`	The request was well-formed JSON but failed schema validation. `details` is keyed by field path.
`429`	Rate limit exceeded. See below.
`500`	Something went wrong on our side. Retry with backoff; if it persists, contact [email protected].

Validation details

details keys are dotted paths into the request. Array items are addressed by index, so recipients.0.email is the email of the first recipient. Query parameters are validated the same way: GET /api/v1/packages?pageSize=500 returns 422 with details.pageSize. A 422 on a body that references something the target resource does not have (an unknown roleIndex, for example) uses the same shape.

Rate limits

All /api/v1 routes share one limit: 120 requests per 60-second window, counted per source IP address. Beyond it the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{ "error": "Rate limit exceeded" }

Retry-After is the number of seconds until the window resets. Wait at least that long before retrying.

async function callWithRetry(url, init, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("Rate limited after retries");
}

import time

import requests


def call_with_retry(session, method, url, attempts=3, **kwargs):
    for _ in range(attempts):
        res = session.request(method, url, timeout=30, **kwargs)
        if res.status_code != 429:
            return res
        time.sleep(float(res.headers.get("Retry-After", "1")))
    raise RuntimeError("Rate limited after retries")

using System.Net;

static async Task<HttpResponseMessage> CallWithRetryAsync(
    HttpClient http,
    Func<HttpRequestMessage> newRequest,
    int attempts = 3)
{
    for (var i = 0; i < attempts; i++)
    {
        var res = await http.SendAsync(newRequest());
        if (res.StatusCode != HttpStatusCode.TooManyRequests) return res;

        var wait = res.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(1);
        await Task.Delay(wait);
    }

    throw new HttpRequestException("Rate limited after retries");
}

Prefer webhooks over polling GET /api/v1/packages/{packageId} to stay well under the limit.

Start here

Concepts

Endpoints

Errors and rate limits

Envelopes

Status codes

Validation details

Rate limits

​Envelopes

​Status codes

​Validation details

​Rate limits

Envelopes

Status codes

Validation details

Rate limits