API token authentication errors

An API token lets your own system or a developer’s script work with Zippendo. You create tokens under Settings → API settings (open the organization menu and click Manage). If a call is rejected, the answer says why.

What you see

401 Unauthorized with Invalid or expired token or Authentication required.
403 Forbidden with Missing required scope or You do not have access to this organization.
429 Too Many Requests with API rate limit of … requests per minute reached.
The call works in the Zippendo app but fails from your script or server.

401: the token is not accepted

Message	Likely cause	What to do
`Authentication required`	No token was sent	Send the token in the `Authorization` header, as shown below
`Invalid or expired token`	The token was mistyped, cut off, deleted or has expired	Check the token as described below. If in doubt, create a new one
`Invalid token type`	Something other than an API token was sent, for example a value copied from the browser	Use the token shown when you clicked Create token

Send the token like this, with the word Bearer and one space in front of it:

Authorization: Bearer zipp_YOUR_TOKEN

Check that:

The token starts with zipp_ and was copied in full, without spaces or line breaks at the end.
The token still exists under API settings. Deleting a token stops it at once.
The token has not expired. The Expires column shows the date. A token created without Expires in (days) never expires.

Zippendo shows a token only once, in API token created. If you no longer have it, create a new token with Add API token and delete the old one. See Create an API token.

403: the token is not allowed to do this

Message	Likely cause	What to do
`Missing required scope`, followed by a permission name such as `write:shipments`	The token was created without that permission	Create a new token and tick the permission under Permissions . The Permissions* column shows what each token can do
You do not have access to this organization.	The organization in the address of the call is not the one the token belongs to	Use the organization the token was created in, or create a token in the other organization
This feature isn’t included in your current plan. Upgrade to use it.	The feature you called is not part of your plan	See Billing and usage

429: too many calls

Each plan allows a number of API calls per minute:

Plan	Calls per minute
Free	10
Standard	60
Growth	200
Pro	1,000
Enterprise	100,000

When you go over, the answer is API rate limit of … requests per minute reached. Please retry in … s. The Retry-After header says how many seconds to wait. Wait that long, then try again, and spread your calls out. More: Rate limits.

You cannot create another token

You’ve reached your plan’s limit. Upgrade your plan or remove something you no longer use. means your plan’s number of API tokens is used up: 2 on Free, 5 on Standard, 10 on Growth, and no limit on Pro and Enterprise. Delete a token you no longer use, or upgrade.

Good habits

Keep tokens on your server. Never put a token in a webshop page or other code that runs in a customer’s browser.
Give each system its own token, with only the permissions it needs. Then you can delete one without stopping the others.

Start here

Integrations & API

Automation & pickups

API token authentication errors

What you see

401: the token is not accepted

403: the token is not allowed to do this

429: too many calls

You cannot create another token

Good habits

​What you see

​401: the token is not accepted

​403: the token is not allowed to do this

​429: too many calls

​You cannot create another token

​Good habits

What you see

401: the token is not accepted

403: the token is not allowed to do this

429: too many calls

You cannot create another token

Good habits