Fixing an error when creating a delivery

When your automation tool or script asks us to create a delivery and something in the request isn't right, we don't create it, and nothing is sent to the recipient. Instead, we answer with a status number, such as 403, and a short code that names the problem:

{
  "error": "unauthorized_recipient",
  "message": "The recipient is not on this account's allowlist."
}

Below we list the most common error codes and discuss what it means and how to fix it.

For more fine grained details, head to the API docs errors page: https://veluril.com/docs/guides/errors

A refused request is not the same as a failed one. A refused request reached us and got one of the codes below, so nothing was created. Once you've fixed the problem, send the same request again, with the same Idempotency-Key. A failed request is one that never got an answer, say after a dropped connection. Send it again with the same key within 24 hours: if we'd already created the delivery, we recognize the key and never send it twice.

401 unauthorized

We didn't recognize the API key. Usually part of the key didn't make it into your tool or script when it was pasted, or the word Bearer is missing from in front of it. The header needs to read:

Authorization: Bearer your-api-key

If the key still says "Not used yet" on your API keys page, it isn't reaching us whole. If the key was revoked, generate a new one. Creating and revoking API keys shows you how.

400 missing_idempotency_key or invalid_body

Something the request needs is missing, or isn't in the shape we expect.

  • missing_idempotency_key means the request didn't include an Idempotency-Key header. Every delivery needs one.
  • invalid_body means the JSON isn't quite right. Check that recipientEmail is a full email address, that items lists at least one bundle, and that each bundleId is the whole ID, like bab5e1c4-7f2a-4d9b-a3c6-51e8b07d920d    . The field names need to match exactly, capitals included.

Creating a delivery from an automation tool or script shows the whole request.

422 unknown_content

The bundle ID is complete, but it doesn't match a bundle we can deliver. The bundle may be in Recycling, it may have no content in it yet, or a character of its ID may have changed on the way. Copy the ID again from the bundle page, as Finding a bundle's ID shows, and check the bundle has content in it.

If the request lists several bundles, one that can't be delivered stops the whole delivery, so check each of them.

403 unauthorized_recipient

Your library is on the Free Explore plan, and the recipient isn't one of your test recipients. Until you launch, deliveries go only to your test recipients, and your own login email always works. To deliver to someone else, add them as a test recipient and wait for them to confirm, or Launch your Library and deliver to anyone.

If the code is account_inactive instead, your account is suspended. Your Billing page shows why, and how to restore it.

409 idempotency_key_conflict

That Idempotency-Key has already created a different delivery. For 24 hours after a delivery is created, its key belongs to it. So a new test, to a different recipient or with a different bundle, needs a new key: TEST-2     after TEST-1    .

429 rate_limited

Too many requests arrived at once. We accept about one request a second, with room for a burst of up to 60 after a quiet spell, shared by every key in your library. The answer includes a Retry-After header with the number of seconds to wait. After that, send the request again.

It worked, but no new delivery was sent

If the request succeeds but no new delivery appears, its Idempotency-Key was one you'd already used in the last 24 hours, with exactly the same details. We recognize it and hand back the delivery we already created, without emailing your recipient again. It's the same protection that stops a duplicate delivery. To send a new one, give it a new key.

If you're writing your own code and want every code in detail, our API errors guide is the place to look.

Related Articles