Brevily API errors: codes, rate limits, retries
Every Brevily API error code and what to do: the error body, 400 field errors, 403 permissions, 429 and RateLimit headers, and retrying writes safely.
On this page
Brevily API errors tell you what went wrong and whether to try again. You get an HTTP status, a stable code your code can branch on, the fields at fault, and a requestId for support. This guide covers the Brevily API error codes you can meet, how rate limits work, and how to retry a write without creating anything twice.
Before you start: you'll want a working call first. See the Brevily API guide, and signing a request if you sign yours.
What a Brevily API error looks like
Every refusal answers its HTTP status and a JSON body like this one, for a link sent with a field the API doesn't know:
{ "code": "VALIDATION_FAILED", "message": "Check the link. colour: Unknown field.", "details": { "fields": { "colour": "Unknown field." } }, "requestId": "17900388544610828411"}codeis stable. Branch on it.messageis written for people and can change. Show it or log it; never parse it.detailsholds the facts, when there are any: the fields at fault, the permission missing, how long to wait.requestId, also sent as thex-request-idheader, finds the request for support. Log it with every refusal.
Brevily API errors: every code and what to do
- 400
VALIDATION_FAILED: a field was refused (each one named indetails.fields), including an unknown body field, an unknown sort, or a filter used the wrong way; or a monthly allowance and its grace are used up. Fix the fields named. For an allowance, see usage limits. - 400
QUERY_INVALID: the query string is past its limits: 50 filters, 5 sort keys, 2,048 characters a value. Narrow the query. - 400
IDEMPOTENCY_KEY_INVALID: theIdempotency-Keyis over 255 characters. Use a UUID. - 401
UNAUTHENTICATED: no key, a wrong, expired or revoked key, a bad signature, or a browser session. Check the key headers or the signature. See signing a request. - 403
ACCESS_DENIED: the key lacks the permission the call needs, or your plan lacks the feature. Readdetails.access; give the key that permission, or check pricing. - 404
NOT_FOUND: no such route, or no such record in the key's organisation. Check the path and the organisation code. - 409
CONFLICT: the record is in a state the call can't change (an expired link can't be disabled), or another request got there first. Read the record again, then decide. - 409
IDEMPOTENCY_IN_FLIGHT: a write with thisIdempotency-Keyis still running. Wait a moment and send it again, with the same key. - 413
PAYLOAD_TOO_LARGE: the body is over 1 MB. Send fewer items per call. - 415
UNSUPPORTED_MEDIA: the body isn't JSON, or has nocontent-type: application/json. Send JSON with that header. - 422
IDEMPOTENCY_MISMATCH: thisIdempotency-Keywas already used, within the day, for a different request. Use a new key for a new write. - 429
RATE_LIMITED: your organisation reached its API limit. WaitRetry-Afterseconds, then send it again.
A 4xx is about the request: change it before sending it again. The two exceptions are 409 IDEMPOTENCY_IN_FLIGHT and 429, which only ask you to wait. Errors on Brevily's side (5xx) are covered at the end.
Fix a 400: field errors
details.fields names each field and what's wrong with it, in words you can show to a person:
"url": "Not a web address. Use one like https://example.com/page.""slug": "That back-half is taken. Case does not matter.""colour": "Unknown field.""sort": "Sort by one of: …; then :asc or :desc.""status": "Filter status by a value (status=…), or a list (status=[a,b])."
A body field the API doesn't know, a sort it can't apply, or a filter used with an operator it doesn't take is refused, not ignored, so it never quietly does nothing. A query parameter it doesn't know at all is different: it's ignored, so a misspelled filter returns the whole list. If a list looks too long, check the filter's spelling.
415: send JSON with its content type
A write's body must be JSON, sent with content-type: application/json (a charset on it is fine). Anything else is refused with 415, and that includes JSON sent without the header: "The API reads JSON only: send the body as JSON, with Content-Type: application/json." A DELETE with no body needs no type. The usual cause is curl: -d on its own sends a form. Add the header:
curl -X POST "$API/$ORG/links" \ -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \ -H "content-type: application/json" \ -d '{"url": "https://www.example.com/offers/spring"}'The key is checked before the body: a missing or wrong key answers 401, and a missing permission 403, before any 415. So fix those first. A POST sent with no body at all isn't a 415 either: it's the call's own 400, such as "url": "A destination is needed." for a link.
401, 403 and 404: who's asking, and for what
- 401 is about the key itself. For a signed request,
details.reasonsays whether the timestamp or the nonce was at fault; see signing a request. - 403 means the key is fine but not allowed.
details.accessnames the permission the call wanted, such asIntegrationManagement:VIEW, so you know exactly what to add. The same 403 comes back for a feature your plan doesn't include. - 404 means there's nothing at that address for this key. A wrong organisation code answers 404 too, and so does another organisation's record, so a 404 is never proof that something was deleted.
Rate limits and the 429 response
API calls are counted for your whole organisation, in two windows: a minute and a day. Every key, personal ones included, shares the same count, so more keys don't give more room. The limits depend on your plan; see pricing. A few things to know:
- A window starts with its first call, not on the clock minute or at midnight.
- Reporting events has its own count, so reporting every sale never blocks your link calls.
- A list counts each item. A
POST /linkswith 100 links counts as 100 calls; items past the limit are refused on their own and the rest are made. - Refused calls count too, so retrying a 429 in a tight loop spends your day's room on refusals.
Every counted answer carries three headers: RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Past the limit, the answer is:
HTTP/1.1 429 Too Many RequestsRetry-After: [seconds]RateLimit-Limit: [limit]RateLimit-Remaining: 0RateLimit-Reset: [seconds]{ "code": "RATE_LIMITED", "message": "Your plan allows [limit] API calls a minute; try again in [seconds] seconds.", "details": { "limit": [limit], "window": "minute", "retryAfter": [seconds] }, "requestId": "…"}Better than waiting for a 429 is slowing down before it. This wrapper pauses when the window is spent, and waits Retry-After if a 429 comes anyway:
const sleep = (s) => new Promise((done) => setTimeout(done, s * 1000));async function callApi(url, options = {}) { for (;;) { const res = await fetch(url, options); if (res.status === 429) { await sleep(Number(res.headers.get('Retry-After') ?? 1)); continue; } if (res.headers.get('RateLimit-Remaining') === '0') { await sleep(Number(res.headers.get('RateLimit-Reset') ?? 1)); } return res; }}Polling for clicks is the most common way to use up a limit. A click webhook tells you as they happen, with no calls at all.
Retry safely with an Idempotency-Key
A read is always safe to send again. A write isn't: if a POST times out, it may have made the link anyway, and sending it again would make two. Add an Idempotency-Key header to the write, with a value of your own (a UUID is ideal), and send the same key with every retry of that write:
- The first call runs. Any retry within 24 hours answers what it did, with the same status and body plus
Idempotency-Replayed: true, and changes nothing. A replay doesn't count against your rate limit. - The same key on a different request (method, path, query or body) answers 422
IDEMPOTENCY_MISMATCH. One key, one write. - While the first call is still running, the key answers 409
IDEMPOTENCY_IN_FLIGHT. Wait and retry. If that call never finished, the key frees itself after two minutes. - A refused call isn't kept. A 400 or 429 sent again with its key runs again, so a fix goes through.
Retry when nothing came back (a timeout or a dropped connection), on 429 and 503 after Retry-After, on 409 IDEMPOTENCY_IN_FLIGHT, and on 500, 502 and 504 with a growing pause. Any other 4xx needs the request changed first.
const { API, ORG, KEY, SECRET } = process.env;const sleep = (s) => new Promise((done) => setTimeout(done, s * 1000));const RETRY = new Set([409, 429, 500, 502, 503, 504]);// One key for every attempt of the same write.async function createLink(body, key = crypto.randomUUID()) { for (let attempt = 1; attempt <= 5; attempt++) { let res; try { res = await fetch(`${API}/${ORG}/links`, { method: 'POST', headers: { 'x-api-key': KEY, 'x-api-secret': SECRET, 'content-type': 'application/json', 'Idempotency-Key': key, }, body: JSON.stringify(body), }); } catch { await sleep(2 ** attempt); // no answer: try again, same key continue; } if (res.ok) return res.json(); const error = await res.json(); if (!RETRY.has(res.status) || (res.status === 409 && error.code !== 'IDEMPOTENCY_IN_FLIGHT')) { throw new Error(`${error.code}: ${error.message} (${error.requestId})`); } await sleep(Number(res.headers.get('Retry-After')) || 2 ** attempt); } throw new Error('No answer after five attempts');}Keep the key with the thing it makes, such as the row in your own database, so a retry after a restart still uses the same one. Signing your requests? Sign each attempt again, with a new nonce; the Idempotency-Key stays the same.
When the problem is on Brevily's side
A 5xx answer is Brevily's, not yours. It carries a general message only, never the details of what failed.
- 500: something failed. Wait and retry with a growing pause; for a write, only with an
Idempotency-Key. - 503: Brevily is being updated, or your organisation is in a maintenance window.
Retry-Aftersays when to try again. - 504: the call took too long. Retry a read; retry a write only with its key.
If it keeps happening, check the status page, then contact support with the requestId.
Common questions
Does a 404 from the Brevily API mean a link was deleted?
No. The Brevily API also answers 404 for a wrong organisation code, a mistyped path, or a record in another organisation. Read the link by its id to be sure.
Do refused calls count against the Brevily API rate limit?
Yes. Every refused call counts in its window, so retrying a 429 in a tight loop spends your room on refusals. A replay of a write with the same Idempotency-Key doesn't count.
Do more API keys give a higher Brevily API rate limit?
No. Every key in your organisation, personal keys included, shares one count per minute and per day. A higher limit depends on your plan; see pricing.
Why does the Brevily API answer 415 Unsupported Media Type?
A write was sent with a content type other than JSON: the Brevily API reads JSON bodies only, sent with content-type: application/json. With curl, -d on its own sends a form, so add -H "content-type: application/json".
Next steps
- Brevily API: the calls themselves, with a first call in Node and Python.
- Sign an API request: the reasons behind a signed request's 401.
- Click webhooks: hear about clicks instead of polling for them.
- MCP server: the same safe retries, with
idempotency_keyon its tools.
On this page