Skip to main content

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

APIShape
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 elseThrown TcError

Codes​

Identity and access​

CodeMeaning
UNAUTHENTICATEDNot signed in (browser), or no X-TC-User on the request (server)
NO_ACCESSThe person isn't allowed to open the app; the fix names the owner
BAD_IDENTITYX-TC-User didn't verify (expired after 5 minutes, wrong audience)
AUTH_UNAVAILABLEThe sign-in service didn't answer normally
NO_REQUESTServer code made a per-user call without the request; pass req or use tc.middleware()
NO_PROJECT_IDENTITYas: 'project' outside a cron/worker service

Configuration​

CodeMeaning
NOT_CONFIGUREDA platform env var is missing; the app isn't running on the platform
SERVER_ONLYA server-only member was called in the browser

Database​

CodeMeaning
DB_ERRORPostgres refused the query; details.code is the SQLSTATE
BAD_SQL_CALLtc.db.sql was called as a function instead of a tagged template

Microsoft 365​

CodeMeaning
M365_ACCESS_DENIEDThe signed-in user can't open the file in SharePoint/OneDrive
M365_NOT_FOUND, M365_TABLE_NOT_FOUND, M365_SHEET_NOT_FOUNDWrong URL, table or sheet
M365_BAD_URLNot a SharePoint/OneDrive or site URL
M365_ERRORAny other Graph error
BAD_MAILmail.send without to or subject
NO_SENDERMail as the app with no owner email

Integrations​

CodeMeaning
ACCESS_PENDINGWaiting for approval; err.request = { id, status, approvers, url }. Works without a redeploy once approved.
ACCESS_DENIEDRefused, or approved narrower
CONNECT_REQUIREDThe person must connect their account once: tc.int.<name>.connect()
INTEGRATION_NOT_FOUND, INTEGRATION_DISABLED, INTEGRATION_NOT_CONFIGUREDThe integration isn't available
VENDOR_ERRORThe 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?