Errors
Every SDK error is a TcError with a stable machine code and a plain-language fix. Show fix to the person, or use it to decide what to do next. Errors are written to teach, so err.message reads as CODE: what went wrong. How to fix it.
TcError
class TcError extends Error {
code: string // e.g. 'M365_ACCESS_DENIED'
reason: string // what went wrong, without the fix
fix: string | null // how to fix it
status: number | null // HTTP status, when there was one
details: unknown // the raw body, SQLSTATE, vendor error…
request?: AccessRequestRef | null // ACCESS_PENDING / ACCESS_DENIED
connectUrl?: string | null // CONNECT_REQUIRED
}
In Python the class has the same fields, with connect_url for CONNECT_REQUIRED.
import { tc, TcError } from '@tenantcloud/sdk'
try {
rows = await tc.m365.excel(url).table('Actuals').rows()
} catch (err) {
if (err instanceof TcError) showError(err.reason, err.fix)
else throw err
}
Where errors appear
| API | Shape |
|---|---|
tc.db.from() / rpc() | Returned as postgrest-js { data, error }. error.hint carries the fix. See Database. |
tc.storage (JavaScript) | Returned as { data, error }, where error is a TcError |
| Everything else | Thrown TcError |
Codes
Identity and access
| Code | Meaning |
|---|---|
UNAUTHENTICATED | Not signed in (browser), or no X-TC-User on the request (server) |
NO_ACCESS | The person isn't allowed to open the app; the fix names the owner |
BAD_IDENTITY | X-TC-User didn't verify (expired after 5 minutes, wrong audience) |
AUTH_UNAVAILABLE | The sign-in service didn't answer normally |
NO_REQUEST | Server code made a per-user call without the request; pass req or use tc.middleware() |
NO_PROJECT_IDENTITY | as: 'project' outside a cron/worker service |
Configuration
| Code | Meaning |
|---|---|
NOT_CONFIGURED | A platform env var is missing; the app isn't running on the platform |
SERVER_ONLY | A server-only member was called in the browser |
Database
| Code | Meaning |
|---|---|
DB_ERROR | Postgres refused the query; details.code is the SQLSTATE |
BAD_SQL_CALL | tc.db.sql was called as a function instead of a tagged template |
Microsoft 365
| Code | Meaning |
|---|---|
M365_ACCESS_DENIED | The signed-in user can't open the file in SharePoint/OneDrive |
M365_NOT_FOUND, M365_TABLE_NOT_FOUND, M365_SHEET_NOT_FOUND | Wrong URL, table or sheet |
M365_BAD_URL | Not a SharePoint/OneDrive or site URL |
M365_ERROR | Any other Graph error |
BAD_MAIL | mail.send without to or subject |
NO_SENDER | Mail as the app with no owner email |
Integrations
| Code | Meaning |
|---|---|
ACCESS_PENDING | Waiting for approval; err.request = { id, status, approvers, url }. Works without a redeploy once approved. |
ACCESS_DENIED | Refused, or approved narrower |
CONNECT_REQUIRED | The person must connect their account once: tc.int.<name>.connect() |
INTEGRATION_NOT_FOUND, INTEGRATION_DISABLED, INTEGRATION_NOT_CONFIGURED | The integration isn't available |
VENDOR_ERROR | The vendor answered with an error; err.details is its body |
Storage
STORAGE_QUOTA_EXCEEDED, STORAGE_FILE_TOO_LARGE, STORAGE_TYPE_NOT_ALLOWED, STORAGE_EXISTS, STORAGE_NOT_OWNER, STORAGE_FORBIDDEN, STORAGE_NOT_FOUND, STORAGE_BUCKET_NOT_FOUND, STORAGE_NOT_PUBLIC, STORAGE_SIGNATURE_EXPIRED, STORAGE_SIGNATURE_INVALID, STORAGE_BAD_PATH, STORAGE_NO_BODY, STORAGE_ERROR, PROJECT_ARCHIVED. See Storage for each fix.
For problems outside the SDK, see Troubleshooting & FAQ.
Was this page helpful?