Common error messages

The codes on this page are not tied to one feature: any page of the dashboard and any operation of the public API can answer with them. The dashboard shows a message for the code; a script reads it from the code field of the error. Codes that belong to one feature, such as scope_exceeds_role or webhook_url_not_allowed, are explained in the article of that feature. The API reference lists the codes each operation returns. The public API and API keys are part of the Premium plan.

Sign-in and permissions

unauthorized

The request does not come from a valid sign-in. In the dashboard, sign in again.

For a script, the API key in the Authorization header is missing, wrong, expired or revoked, or its owner has left the organization. Create a new key on your profile’s Integrations tab (API keys and the public API).

forbidden

Your current role, your teams or a company setting do not allow this action. Rights are checked against your role as it is at the moment of the request, so a change of role takes effect right away. If you need the action, ask an owner or an admin of your organization.

For a script, the key does not have the scope the operation needs, or its owner’s current role does not allow the request. A key never does more than its owner’s current role; the action field of the error names the permission that was missing.

email_verification_required

You created your account yourself and did not verify your e-mail address within 24 hours of creating it. Until you do, the dashboard shows only a page that asks you to verify, and the desktop app’s requests are refused too. Signing out and the help center still work.

1. Open the verification link in the e-mail we sent you when you signed up. Check your spam folder too.
2. No e-mail, or the link no longer works? Resend it from the page in the dashboard and open the new link.
3. Everything works again as soon as the address is verified; you do not need to sign in again.

The address cannot be changed before it is verified. To use another address, sign out and sign up again with it.

For the first 24 hours after sign-up everything works, and a banner shows the time left. People who joined through an invitation link, people whose Google or Microsoft account or company sign-in already confirmed the address, and users created by SCIM provisioning do not need to verify. If the address is still not verified 72 hours after sign-up, the account is deleted, together with the organization it created if nobody else has joined it (admin quick start).

For a script, an API key whose owner has this problem gets the same error; its dueAt field gives the time the 24 hours ended.

Requests that cannot be carried out

not_found

What you asked for does not exist, for example because it was deleted in the meantime. Reload the page. A script should check the id it sent.

validation_failed

Something you entered is not valid. The dashboard marks the fields to correct. For a script, the errors field of the error lists each field with its problem.

invalid_request

A parameter of the request is missing or malformed, for example a date that is not a date. In the dashboard, reload the page and try again; if it keeps happening, report a problem.

Changes made at the same time

version_conflict

Someone else changed the same thing after you opened it, and your change would overwrite theirs. Reload, check what changed and make your change again.

For a script, the If-Match version it sent is no longer current. Read the resource again, which returns its current version in the ETag header, and repeat the change with that version.

precondition_required

For scripts: the operation changes a resource that has a version and needs an If-Match header with the ETag you read. Read the resource first and send its ETag in If-Match.

conflict

The change does not fit the current state of the data, for example because another change was saved at the same moment. Reload and try again.

idempotency_key_reused

For scripts: the Idempotency-Key header was already used in the last 24 hours for a different request: another method, address, query or body, or another person’s key. Use a new value for each new request. Send a value again only to repeat the same request unchanged; the API then returns the first answer again instead of doing the work twice.