Errors

Errors use one envelope across the API:

{
  "error": {
    "type": "ForbiddenError",
    "title": "Forbidden",
    "detail": "The transcriptions.read scope is required.",
    "code": "INSUFFICIENT_SCOPE",
    "request_id": "req_9bfbe80ac1f24e0a9d5b1e5e7a0f2c11"
  }
}

Branch on code

code is the stable, machine-readable field. It does not change with wording, translation or refactoring.

title and detail are human text and may be reworded between releases. type is the error class and is stable, but coarser than code — several codes share one class. Never parse detail.

Quote request_id when contacting support: it identifies the exact request in our logs.

Codes

HTTP	code	Meaning
400	INVALID_LIMIT	Page size outside 1–100.
400	INVALID_DATETIME	A timestamp is not RFC 3339 with an explicit offset.
400	INVALID_FILTER	A filter value or combination is unsupported.
400	INVALID_CURSOR	The cursor was edited, or the filters changed mid-traversal.
400	INVALID_REQUEST	Request validation failed, including unknown query parameters.
401	MISSING_ACCESS_TOKEN	No bearer token was sent.
401	INVALID_ACCESS_TOKEN	The token is invalid, expired, or its credential was revoked — or, for a user credential, its owner is no longer an active member.
403	INSUFFICIENT_SCOPE	The token does not carry the scope the route requires, or a user credential’s owner lost email or WhatsApp access.
403	API_ACCESS_DISABLED	The company does not have API access enabled.
403	AI_COLLABORATORS_DISABLED	A connection of one of Salesbud‘s own apps, such as the AI collaborators, in a company without that feature. Returned by /oauth/token and by the approval of the consent screen.
403	API_CLIENT_PENDING_APPROVAL	The token belongs to a connection made by signing in with OAuth that an administrator has not approved yet. Nothing to retry until it is approved. The detail reads “The API client is waiting for administrator approval.”.
404	RESOURCE_NOT_FOUND	Absent, owned by another company, outside a user credential’s view, or addressed in the wrong collection.
413	PAYLOAD_TOO_LARGE	The request body exceeds the accepted size.
415	UNSUPPORTED_MEDIA_TYPE	Wrong content type — most often JSON sent to /oauth/token.
429	RATE_LIMIT_EXCEEDED	A rate-limit policy rejected the request.
503	SERVICE_UNAVAILABLE	A fail-closed dependency is unavailable. Retry with backoff.
503	AUDIT_UNAVAILABLE	A successful read could not be recorded in the audit trail, so it was not returned.

Unknown identifiers are always 404

An id belonging to another company returns 404 RESOURCE_NOT_FOUND, not 403. The API does not confirm that a resource exists somewhere else — a 403 would leak that fact to anyone probing ids.

The token endpoint is different

POST /oauth/token returns the OAuth 2.0 error shape that RFC 6749 §5.2 mandates, so standard OAuth clients keep working:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Besides invalid_request, invalid_client, invalid_scope and unsupported_grant_type, the OAuth connection grants answer invalid_grant when a code or a refresh token is expired, already used, does not match the PKCE verifier, names a different resource than the authorization, or is no longer backed by an active connection or an active owner. Connect again.

What is never in an error

Stack traces, source paths, tokens, secrets, request bodies and domain payloads are never returned. An unexpected failure returns a fixed generic message with a request_id; the detail stays in our logs.

Retrying

Status	Retry?
400, 403, 404, 413, 415	No. The request will fail identically.
401	Once, after re-issuing the token. For OAuth connections, renew with the refresh token; if that fails, reconnect.
429	Yes, after Retry-After.
503	Yes, with exponential backoff and jitter.