Awesomate docs v0.27.0

Reference

Errors

AwesomateError, what each error code means, and which sentence to show the person.

Every failure is an AwesomateError. Branch on code, show personMessage to the person when it is there, and log message and serverCode for yourself.

import { AwesomateError } from '@awesomate/sdk';

try {
  await app.call('accept_quote', { job: job.id });
} catch (err) {
  if (err instanceof AwesomateError && err.code === 'not_found') showMessage('That quote is no longer open.');
  else throw err;
}

Codes

`code`	What it means
`unauthenticated`	No valid sign-in or token. In an app, sign the person in again; on a server, check the token.
`forbidden`	Signed in, but not allowed: the role, or a key that does not cover this kind.
`not_found`	Nothing there that this caller may see. A record they may not read looks exactly like one that does not exist.
`validation`	A value the kind does not accept, or a query that names a column it cannot read. `field` names it.
`consent_blocked`	The account has switched off what this call needs, in its Privacy or Features settings. Only the owner can switch it on, in the hub.
`rate_limited`	Too many calls in a short time. Wait a little and try again.
`conflict`	Something changed while the call ran (a kind's fields were edited). A read is retried once for you.
`unavailable`	Anything else, including the hub being briefly unreachable. `serverCode` has the hub's own detail: `payment_suspended` means the account is on hold for an unpaid bill, and its apps and keys stop until the owner pays in the hub (do not retry in a loop).
`feature_unavailable`	The account does not have this feature. `reason` says why (not_released, turned_off_by_awesomate, not_on_plan, switched_off_by_you), `feature` names it, and `upgrade` is set when a plan includes it. Say `message` and stop; never retry.
`upgrade_required`	This needs a higher plan. `requiredPlan` names it, and `upgrade` gives the hub page when the hub sent one.
`scope_missing`	The token lacks a scope this call needs. `missingScopes` names them: make a token with them in the hub.

AwesomateError

Every failure from the hub. message is for you, the developer; personMessage, when the hub sent one, is the sentence to show the person using your app. A refusal over a feature, a plan or a token's scopes says what it is about in reason, feature, missingScopes, upgrade and requiredPlan.

Property	Type
`message`	`string`	For you, the developer.
`cause` (optional)	`unknown`
`code`	`"unauthenticated" \| "forbidden" \| "not_found" \| "validation" \| "consent_blocked" \| "rate_limited" \| "conflict" \| "unavailable" \| "feature_unavailable" \| "upgrade_required" \| "scope_missing"`	Why it failed.
`feature` (optional)	`string`	With feature_unavailable: the feature's key.
`field` (optional)	`string`	The column or parameter a validation error is about.
`message`	`string`
`missingScopes` (optional)	`string[]`	With scope_missing: the scopes the token lacks. Make a token with them in the hub.
`name`	`string`
`personMessage` (optional)	`string`	A sentence for the person using the app, when the hub sent one (a refused voice call: "You've used today's voice time").
`reason` (optional)	`string`	With feature_unavailable: why the account does not have the feature (not_released, turned_off_by_awesomate, not_on_plan, switched_off_by_you).
`requiredPlan` (optional)	`string`	The plan this needs, when the hub named one.
`serverCode` (optional)	`string`	The hub's own code, unmapped.
`stack` (optional)	`string`
`status`	`number`	The HTTP status, or 0 when the SDK refused before sending.
`upgrade` (optional)	`{ plan: string; url: string }`	The plan that includes it and the hub page to upgrade on, when the hub said.
`stackTraceLimit`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

ErrorCode

Why a call failed, one of a fixed list: unauthenticated, forbidden, not_found, validation, consent_blocked, rate_limited, conflict, unavailable, feature_unavailable, upgrade_required, scope_missing. The hub's own detail is in serverCode.

type ErrorCode = typeof ERROR_CODES[number]