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"
}
}
Field Meaning 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.
Type Status What 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.
Code Status Cause 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.
Code Status Cause 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 .
Code Status Cause 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.
Code Status Cause 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.
Code Status Cause 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.
Code Status Cause 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.
Code Status Cause internal_error500An unexpected failure, including a request that ran over 10 seconds.
JavaScript Python
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.
Was this page helpful? ๐ ๐