Letterby Docs

Errors

The error format, every error code and how to handle it.

Every error has the same JSON shape and a matching HTTP status.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Payout must be at least $1.",
    "param": "payoutCents",
    "request_id": "req_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b",
    "docs_url": "https://letterby.com/docs/api/errors#invalid_request"
  }
}
FieldMeaning
typeThe error family. Branch on this for broad handling.
codeThe exact cause. Branch on this for specific handling.
messageA sentence for developers. Do not parse it.
paramThe request field at fault, when there is one.
request_idQuote this to support. Also sent as the X-Request-Id header.

Types

TypeStatusWhat to do
invalid_request_error404, 413, 422Fix the request. Retrying unchanged fails again.
authentication_error401Check the key.
authorization_error403Use a key with more access.
rate_limit_error429Wait for Retry-After seconds, then retry.
idempotency_error409, 422See Idempotency.
api_error500Our fault. Retry with backoff.

Codes

Authentication

CodeStatusCause
missing_api_key401No bearer key in the Authorization header.
invalid_key401Unknown or revoked key, suspended team, or the key's creator lost the owner or admin role.
invalid_api_key401The key's team no longer exists.
insufficient_scope403The key's access level does not cover this endpoint.

Requests

CodeStatusCause
invalid_request422A field is missing or invalid. param names it.
invalid_json422The body is not valid JSON.
invalid_cursor422starting_after is not a cursor returned by the API.
payload_too_large413The body is over 32 KB.
resource_missing404Nothing with that id exists in your team.
rate_limit_exceeded429Too many requests. See Rate limits.

Offers

CodeStatusCause
publication_mismatch422publicationId in the body differs from the publication in the URL.
invalid_status_transition422The status change is not allowed through the API. See below.
insufficient_balance422Activating needs a balance of at least one payout. Add funds first.
budget_below_spent422The new budgetCents is lower than what the offer already spent plus the payouts held by subscribers still in screening.
monthly_budget_below_spent422The new monthlyBudgetCents is lower than this month's spend plus the payouts held by subscribers still in screening.
pilot_cap_exceeded422The budget is above the current launch-period cap. message gives the cap.

Status changes the API refuses with invalid_status_transition:

  • Archiving an offer. Archive it in the dashboard, which also ends its agreements.
  • Changing an archived offer.
  • Activating an offer that is out of funds. It resumes by itself when you add funds.
  • Activating an offer that Letterby paused.
  • Ending an agreement that was declined.

Agreements

CodeStatusCause
offer_not_available422The offer cannot be accepted by this publication.

offer_not_available covers every reason an offer cannot be accepted: it is not active, it is your own, you already accepted it, the advertiser blocked or removed your publication, or your team is not an approved partner yet. The API does not say which.

Webhooks

CodeStatusCause
invalid_webhook_url422The URL is not allowed. message ends with the reason.

Reasons: https_required, invalid_url, url_too_long, missing_host, blocked_host, private_ip, no_credentials_in_url.

Idempotency

CodeStatusCause
idempotency_in_flight409A request with this key is still running. Retry shortly.
idempotency_key_reused422The key was used with a different body, or its format is invalid.

Server

CodeStatusCause
internal_error500An unexpected failure, including a request that ran over 10 seconds.

Handle errors

async function letterby(path, init = {}) {
  const res = await fetch(`https://api.letterby.com/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.LETTERBY_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (res.ok) return res.json();

  const { error } = await res.json();
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return letterby(path, init);
  }
  throw Object.assign(new Error(error.message), error);
}

Retry 429 and 500. Do not retry other 4xx errors without changing the request.

On this page