API error reference

What each error from the SpeakUp Public API means and how to resolve it. Errors are grouped by HTTP status code, since that is what your integration sees first.

SCIM endpoints return errors in a different format. See SCIM Users API and SCIM Groups API.

On this page: 400 Bad Request · 401 Unauthorized · 403 Forbidden · 404 Not Found · 500 Internal Server Error · Named errors

400 Bad Request

The request was understood but could not be processed. Almost always the request body on a PUT or PATCH.

Cause	What to do
The request body is missing.	Both PUT and PATCH require a body.
The body is empty, malformed, or contains unrecognised fields.	Check the field names against Updating Issues.
A PUT request is missing required fields.	The response names the missing fields. Retrieve the Issue first and resend its current values, or use PATCH instead.
A PUT request is missing required custom fields.	The response names the missing `issueFieldId` values. PUT requires every custom field defined for the Issue type.
The body contains fields the Issue type does not support.	Sub Issues reject `domain`, `labels`, and `issueFields`. Check the Issue's `type` first.
The assignee has no access to the Issue.	Choose a User with access to the Issue's domain.
The domain is archived.	Archived domains cannot be set on an Issue. Choose an active domain.

401 Unauthorized

The request carried no valid token.

Cause	What to do
The token is missing from the request.	Send it as `Authorization: Bearer <ACCESS_TOKEN>`.
The token is invalid.	Request a new token. See how do I make my first API request?
The token has expired.	Tokens are valid for 1 hour. Build token refresh into your integration rather than storing one token.

A 401 on a request that worked an hour ago is almost always expiry.

403 Forbidden

The token is valid, but the integration is not permitted to do this.

Cause	What to do
The Public API package is not enabled for your organisation.	Contact your Customer Success Manager.
The integration has read only access and the request writes.	Updating Issues requires full access for Issues. Access levels are set when the App Integration is created and shown on its detail page. See how do I create an App Integration and get API credentials?
The integration has read only access for Users and Groups and the request provisions.	SCIM provisioning requires full access for Users and Groups.

The difference between 401 and 403 is worth internalising. A 401 means try again with a new token. A 403 means the token is fine and the integration's permissions need changing, so retrying will never help.

404 Not Found

Something referenced in the request does not exist, or the integration cannot see it.

Cause	What to do
The Issue does not exist, or the integration cannot access it.	Check the ID against the list endpoint in Retrieving Issues.
The `assigneeId` does not exist.	The User must exist, be enabled, and not be a service or support user.
The `status` does not exist.	Statuses come from the workflow for the Issue type.
The `domain` does not exist.	Domain names are matched exactly, including case.
One or more `issueFieldId` values do not exist for the Issue type.	Retrieve the Issue to get its valid field IDs. See Retrieving Issues.

A 404 does not distinguish between an Issue that does not exist and one your integration cannot reach. Both return the same response, so an unexpected 404 on an ID you believe is valid is worth checking against the list endpoint before assuming the Issue is gone.

500 Internal Server Error

Something failed on the SpeakUp side. The request may have been valid.

Retry once. If it persists, contact SpeakUp support with the endpoint, the approximate time, and the Issue ID if the request involved one.

Named errors

Some responses carry a named error. These are the ones you are most likely to encounter.

Name	Status	Meaning
`TokenExpiredError`	401	The access token is older than 1 hour.
`FeatureNotEnabledError`	403	The Public API package is not enabled for your organisation.
`ForbiddenError`	403	The integration's access level does not permit this request.