Errors

TeamUp uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a class is not open for registration, etc.). Codes in the 5xx range indicate an error with TeamUp's servers (these are rare).

Error Response Format

Example

{
  "code": "parameter_invalid",
  "field_errors": {
    "offering_type": ["The offering type ID was not found"],
    "non_field_errors": ["Start date cannot come after end date"]
  },
  "message": "You request was invalid",
  "type": "invalid_request_error"
}

• code: A short string indicating the error code. Useful for handling certain errors programmatically.
• field_errors: Object where each key matches a field name in the request body, with one or more messages explaining why the provided value is invalid. A non_field_errors key is included for validation errors that are not specific to a single field.
• message: A human-readable message providing more details about the error..
• type: The type of error returned. One of invalid_request_error, conflict, event_check_failure

HTTP Status Code Summary

Status Code	Status	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	Authentication failed due to invalid credentials.
403	Forbidden	The identity linked to the credentials (often a user) doesn't have permission to access the endpoint.
404	Not Found	The requested resource doesn’t exist.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on TeamUp's end. (These are rare.)

Error Code Reference

Beyond the HTTP status, every error response includes a code string (see Error Response Format) that identifies exactly what went wrong. The codes below are the ones developers hit most often.

Most of them — including most 403 responses — are not caused by the permissions configured for a user. They usually mean the request was authenticated or scoped differently than you intended: the wrong token type, the wrong Authorization prefix, or a missing TeamUp-Request-Mode / TeamUp-Provider-ID header. See Authentication for how tokens, modes, and these headers fit together.

Quick Reference

Code	Status	What it usually means
permission_denied	403	The role the API resolved for your request isn't allowed to perform this action.
mode_not_allowed	403	Your credentials can't operate in the request mode you specified.
provider_invalid	403	The provider isn't accessible to your token, or provider mode was used without staff access.
provider_header_invalid	403	TeamUp-Provider-ID doesn't identify an active provider you can access.
customer_invalid	403	The customer targeted by the request doesn't exist, is deleted, or isn't accessible to you.
provider_header_missing	400	No provider was specified by a header or by the token itself.
mode_invalid	400	TeamUp-Request-Mode was set to something other than provider or customer.
authentication_failed	401	Your credential was recognized but is invalid or expired.

permission_denied (403)

"As a unregistered customer, you are not allowed to perform this action (list)."

What it means: The endpoint's access policy denied the request for the role the API resolved you to. The message names that role — unregistered customer, registered customer, or staff member/manager at the provider — and the trailing parenthesis names the action you attempted.

Most common cause: The API resolved your request to a different role than you intended:

• "As a unregistered customer …" when you expected staff or customer access. Your credentials were not applied to the request at all. The usual culprit is the Authorization header prefix: use Bearer (Authorization: Bearer <token>). If the prefix is missing, misspelled, or anything else, the request is silently treated as unauthenticated — you get this 403, not a 401. It can also mean the authenticated user has no customer profile at the provider you targeted.
• "As a staff member/manager …" on a customer action. Some actions (for example, registering a customer for an event) run in customer mode. Send TeamUp-Request-Mode: customer and identify the customer, rather than calling it as staff.

Fix: Check the role named in the message against the roles the endpoint's reference documentation says can perform the action, then work out why the API saw you as that role — usually an Authorization prefix problem or a missing/incorrect TeamUp-Request-Mode header.

mode_not_allowed (403)

"You are not able to make requests in the specified mode."

What it means: You asked for a request mode (usually TeamUp-Request-Mode: provider) that your credentials cannot operate in.

Most common cause: The token is not the type you think it is. Provider mode requires either an M2M token created for the business, or an OAuth token for a user who is a staff member at that provider. A customer's OAuth token can never make provider-mode requests.

Fix: Recreate the token as the right type — an M2M token from the business dashboard for server-to-server access, or an OAuth flow completed by a staff user — and keep TeamUp-Request-Mode consistent with that token type.

provider_invalid (403)

"You don't have access to this Provider. It does not exist, or access has been revoked."

or

"Cannot perform request in provider mode because the authenticated user is not a staff member at the provider."

What it means: The provider the request is scoped to isn't one your token or application has access to, or you requested provider mode with a user who has no staff access there.

Most common cause: The TeamUp-Provider-ID header names a provider your token was not created for (each token is scoped to specific providers), or you sent TeamUp-Request-Mode: provider with a token whose user isn't staff at that provider.

Fix: Verify the TeamUp-Provider-ID value matches the provider the token was issued for. For provider mode, use an M2M token or an OAuth token belonging to a staff member at that provider.

provider_header_invalid (403)

"The Teamup-Provider-ID header is invalid. The Provider does not exist, or you cannot access it, or access has been revoked."

What it means: The TeamUp-Provider-ID header value doesn't identify an active provider.

Most common cause: The value isn't the provider's numeric ID (for example, a business name or slug was sent instead), or the ID doesn't exist or belongs to an inactive account.

Fix: Send the provider's numeric ID.

customer_invalid (403)

"The Customer does not exist, is deleted, or you do not have access to it."

What it means: The customer the request targets — via the TeamUp-Customer-ID header or the active_customer query parameter — can't be used.

Most common cause: The customer ID doesn't exist at the provider the request is scoped to, refers to a deleted customer, or names a customer your credentials aren't allowed to act for (a customer token can only act for the customer's own family).

Fix: Use a customer ID that belongs to the provider in TeamUp-Provider-ID, and make sure your token is allowed to act for that customer.

provider_header_missing (400)

"You must supply the Teamup-Provider-ID header."

What it means: The request didn't specify which provider (business) it applies to, and the token itself isn't scoped to a single provider.

Fix: Send the TeamUp-Provider-ID header with the provider's numeric ID.

mode_invalid (400)

"The value of the TeamUp-Request-Mode header must be one of: provider, customer."

What it means: The TeamUp-Request-Mode header was present but not a valid value.

Fix: Use exactly provider or customer (lowercase).

authentication_failed (401)

"The token you provided is expired or invalid"

What it means: The Authorization header used the Bearer prefix, but the credential itself failed — it's expired, revoked, malformed, or contains stray whitespace ("Invalid token header. Token string should not contain spaces.").

Fix: Issue a fresh token and check the header formatting. Note the flip side: if the Authorization prefix is wrong, you will not get this 401 — the request proceeds unauthenticated and typically fails later with a 403 permission_denied naming you an "unregistered customer".

Debugging a 403

Work through these in order — they resolve the vast majority of unexpected 403 responses:

1. Check the Authorization prefix. Use Authorization: Bearer <token> for both M2M tokens and OAuth access tokens. Any other prefix makes the API treat the request as unauthenticated without returning a 401.
2. Check the token type against the mode. Provider mode requires an M2M token or an OAuth token for a staff member at the provider. If provider mode keeps failing, the token type — not your code — is usually the problem.
3. Send TeamUp-Request-Mode explicitly. If you omit it, the API infers a mode: M2M tokens always run in provider mode; for user tokens the mode is inferred from the user's profiles at the provider, defaulting to customer mode when ambiguous. An explicit header removes the guesswork.
4. Verify TeamUp-Provider-ID. It must be the numeric ID of a provider your token was created for.
5. Read the error message. The role it names ("unregistered customer", "registered customer", "staff member/manager") is what the API resolved your request to — if that isn't who you meant to be, the problem is in steps 1–4, not in the endpoint.