Errors
An app catches each refusal of Tempo ID, and branches on its reason.
Overview
Each call throws Accounts.RequestError when Tempo ID refuses a request. Its reason is the refusal's stable name, its code the OAuth error code, and its message the fault and the fix.
The demo reads the user of an access token that Tempo ID did not issue, and shows the error. The read needs no sign-in, and changes nothing.
Walkthrough
Create the instance
import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Catch the error
The handler throws again each error that is not an Accounts.RequestError, such as Accounts.SignedOutError without a session. It returns the message of each refusal that it does not handle.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function readConnection() {
try {
const { accessKeys } = await accounts.connection.get()
return `The app holds ${accessKeys.length} access keys.`
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
return error.message
}
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Branch on the reason
A message's wording may change, and a reason does not. invalid_token refuses an expired or revoked access token, or another app's. Reasons lists each reason.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function readConnection() {
try {
const { accessKeys } = await accounts.connection.get()
return `The app holds ${accessKeys.length} access keys.`
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
if (error.reason === 'invalid_token') return 'Sign in again.'
return error.message
}
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Retry a temporary failure
A rate limit and a failed service have different reasons, and share the code temporarily_unavailable. A branch on the code handles both.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function readConnection() {
try {
const { accessKeys } = await accounts.connection.get()
return `The app holds ${accessKeys.length} access keys.`
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
if (error.reason === 'invalid_token') return 'Sign in again.'
if (error.code === 'temporarily_unavailable') return 'Try again later.'
return error.message
}
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Use cases
Each use case reads one property of Accounts.RequestError, or catches another error class of the package.
Handle a refusal without a reason
Tempo ID's OAuth endpoints return no reason, so the app branches on the code. A refresh with a revoked or expired refresh token fails with invalid_grant.
tokens.userInfo sets the reason invalid_token itself, for each access token that Tempo ID refuses.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function refresh() {
try {
await accounts.session.refresh()
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
if (error.code === 'invalid_grant') console.log('Sign in again.')
}
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Detect a refusal before a request
The package refuses some options, such as a past expiry, before any request. The error holds Tempo ID's reason, and status 0.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function signIn() {
try {
await accounts.dialog.signIn({
accessKey: { expiry: 1, limits: [{ limit: '100', token: 'ousd' }] },
})
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
console.log(error.reason, error.status) // 'expiry_passed', 0
}
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Show the field at fault
field names the request field at fault as a dotted path, such as the limit of an access key. A form shows the message beside that field.
import { Accounts } from 'accounts'
export function fieldError(error: Accounts.RequestError, name: string) {
return error.field === name ? error.message : undefined
}Wait out a rate limit
meta holds the values that the refusal compared. For rate_limited, it holds the seconds to wait, if Tempo ID knows them.
import { Accounts } from 'accounts'
export function wait(error: Accounts.RequestError) {
if (error.reason !== 'rate_limited') return undefined
return Number(error.meta?.retryAfter ?? 60)
}Link the explanation
uri holds the link to Tempo ID's description of the error, as the Reasons table shows. A support page or a log shows it beside the message.
import { Accounts } from 'accounts'
export function describe(error: Accounts.RequestError) {
if (!error.uri) return error.message
return `${error.message} See ${error.uri}.`
}Restart a failed sign-in
A sign-in can fail after the user's code or passkey verified, such as when Tempo ID refuses the authorization. The error then has signedIn, and the instance empties its session.
The emailed code verified already, so the app requests a new one. Without signedIn, the session stays as it was.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function signIn(email: string, code: string) {
try {
await accounts.email.signIn({ code, email })
} catch (error) {
if (!(error instanceof Accounts.RequestError)) throw error
if (error.signedIn) await accounts.email.sendCode({ email })
return error.message
}
}import { Accounts } from 'accounts'
import { email } from 'accounts/plugins'
export const accounts = Accounts.create({
chain: 'testnet',
clientId: 'example-app',
plugins: [email()],
})Ignore a closed dialog
A closed dialog is no refusal. dialog.signIn throws a DOMException named AbortError for it, and for a sign-in that a later one replaces. A closed passkey prompt is none either: passkey.signIn, passkey.register, and email.signIn with link throw an Error named AbortError for it, since React Native has no DOMException. The app checks the name alone. An authenticator that already holds one of the user's passkeys refuses a new one, so passkey.register throws an Error named InvalidStateError, and the app offers a sign-in with that passkey instead.
If another sign-in or a sign-out completes first, it throws Accounts.SupersededError. The app ignores both.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export function SignIn() {
async function signIn() {
try {
await accounts.dialog.signIn()
} catch (error) {
if (error instanceof Error && error.name === 'AbortError') return
if (error instanceof Accounts.SupersededError) return
throw error
}
}
return (
<button onClick={signIn} type="button">
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Send only when signed in
A transaction without a session throws Accounts.SignedOutError. If a refused refresh token ended the session, its cause holds that refusal.
A transaction from a session without an access key throws Accounts.AccessKeyRequiredError. The app then signs the user in with an access key.
import { Accounts } from 'accounts'
import { parseUnits } from 'viem'
import { Addresses } from 'viem/tempo'
import { accounts } from './tempo.config.js'
export async function send() {
try {
await accounts.token.transferSync({
amount: parseUnits('1', 6),
to: '0x000000000000000000000000000000000000dEaD',
token: Addresses.ousd,
})
} catch (error) {
if (error instanceof Accounts.SignedOutError) return 'Sign in to send.'
if (error instanceof Accounts.AccessKeyRequiredError)
return 'Sign in with an access key to send.'
throw error
}
}import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
export const accounts = Accounts.create({
chain: 'testnet',
plugins: [viem()],
})Handle an ended retry
If a transaction fails for its access key, its limit, or its balance, the viem plugin shows a screen that resolves it, then sends again. If the user closes the screen, the call throws Plugins.viem.RetryClosedError.
If the sign-in for a new access key returns another account, the call throws Plugins.viem.RetryAccountError. The app matches both by name.
import { parseUnits } from 'viem'
import { Addresses } from 'viem/tempo'
import { accounts } from './tempo.config.js'
export async function send() {
try {
await accounts.token.transferSync({
amount: parseUnits('1', 6),
to: '0x000000000000000000000000000000000000dEaD',
token: Addresses.ousd,
})
} catch (error) {
const { name } = error as Error
if (name === 'Plugins.viem.RetryClosedError') return 'The transaction did not send.'
if (name === 'Plugins.viem.RetryAccountError') return 'Sign in with the same account.'
throw error
}
}import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
export const accounts = Accounts.create({
chain: 'testnet',
plugins: [viem()],
})Ignore a revoked access key
accessKey.revokeSync throws Accounts.RevokedError if the chain holds the access key revoked already. A sign-out ignores it, since the access key signs nothing.
import { Accounts } from 'accounts'
import { accounts } from './tempo.config.js'
export async function signOut() {
const { session } = accounts.session.status.get()
const accessKey = session?.accessKey?.keyAuthorization.keyId
try {
if (accessKey) await accounts.accessKey.revokeSync({ accessKey })
} catch (error) {
if (!(error instanceof Accounts.RevokedError)) throw error
}
await accounts.signOut()
}import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
export const accounts = Accounts.create({
chain: 'testnet',
plugins: [viem()],
})Reasons
The table lists each RequestError.Reason. Each links Tempo ID's description, which names its code, field, and meta.
The error's uri holds the same link, as Link the explanation shows. Each call's TSDoc lists its reasons.
| Reason | Fault | Fix |
|---|---|---|
access_key_changing | Another request changes the same limit or the scopes. | Retry after it ends. |
access_key_endpoint_failed | An API's access key endpoint failed at the approval. | Approve again. |
access_key_pending | The access key has an unregistered key authorization with other limits or scopes. | Request a new access key. |
access_key_taken | Another app holds the access key for the Tempo Account. | Request a new access key. |
allowance_redeemed | The API redeemed the connection's allowance for another access key. | Use the access key of meta.address. |
already_decided | The user already approved or denied the device code. | Request a new code. |
app_exists | Another OAuth app has the client ID. | Choose another client ID. |
authorization_expired | The authorization request that a Tempo ID page continues is forged or expired. | Start the sign-in again. |
backend_sign_in_not_permitted | The app has no client secret or keys, or no backend sign-in. | Sign in through a redirect. |
body_too_large | The body exceeds 65,536 bytes, or a pushed request 8,192 bytes. | Send a smaller body. |
challenge_not_permitted | A headless request holds a challenge without the tempo-id:sign scope. | Send the challenge through a redirect. |
config_conflict | The chain's account configuration differs from Tempo ID's. | Read the account again. |
configurable_accounts_disabled | The deployment has no configurable accounts on the chain. | Select a chain of meta.configured. |
connection_mismatch | A redemption's nonce or public key does not match the prepared access key. | Send the newest nonce and its public key. |
consent_required | A redirect requests an access key with prompt=none, which shows no approval page. | Remove prompt=none. |
cross_site_request | A form, or a write without a body, came from another site. | Send JSON from an allowed origin. |
duplicate_limit | Two limits name one token. | Limit each token once. |
duplicate_scope | Two scopes name one call on one target. | Name each call once. |
embed_not_permitted | A native or device app frames the embedded sign-in. | Sign in through a redirect. |
employee_required | An employee app's request holds no active employee identity. | Send an admitted request's identity assertion. |
empty_limits | limits is empty. | Name a token. |
empty_scopes | scopes is empty. | Name a call. |
expiry_exceeds_maximum | A headless access key lasts longer than a year. | Use an earlier expiry. |
expiry_passed | The expiry is in the past. | Use a future time, or a duration. |
foreign_account | The user holds no such Tempo Account in the app's realms. | Name one of the user's Tempo Accounts. |
funding_unavailable | The deployment sells no MACH. | Choose another deposit method. |
google_unavailable | The deployment offers no Google sign-in. | Sign in with an emailed code or a passkey. |
insufficient_balance | The Tempo Account cannot pay the network fee to revoke or change an access key. | Add funds. |
invalid_access_key_endpoint | An access key endpoint is not an https URL on its resource's origin. | Register such a URL. |
invalid_app | An OAuth app value is not valid. | Fix the value that the message names. |
invalid_chain | The chain ID is 0. | Use a Tempo chain ID. |
invalid_client | The app is unknown or disabled, or its credentials are missing or wrong. | Send an enabled app's credentials. |
invalid_client_attestation | A native app's client attestation is missing, or does not verify. | Attest the instance key again. |
invalid_client_metadata | A dynamic client registration names a value that Tempo ID refuses. | Leave out the value that field names. |
invalid_code | The emailed code is wrong, expired, or used. | Request a new code. |
invalid_dpop_proof | A DPoP proof is missing, invalid, or replayed. | Send a new proof, or sign in again. |
invalid_expiry | The expiry is 0, not a whole number of seconds, or in milliseconds. | Use a future time in whole seconds, or a duration. |
invalid_field | A request field is missing or malformed. | Fix the field that field names. |
invalid_id_token_hint | A logout's hint is not an ID token that Tempo ID signed for the app. | Send the app's ID token. |
invalid_origin | A headless request came from an origin that the app does not allow. | Call from a page on the app's origin. |
invalid_period | A limit's period is not a whole number of seconds. | Use whole seconds, a duration, or 0 for a one-time limit. |
invalid_public_key | The public key is not a valid point. | Send an uncompressed public key, or an address. |
invalid_realm | A realm value is not valid. | Fix the value that the message names. |
invalid_recipients | A scope names the zero address, one address twice, or recipients on a call that takes none. | Name each recipient once. |
invalid_redirect_uri | A dynamic client registration names no redirect URI, more than 10, or one that Tempo ID refuses. | Name a public https URI. |
invalid_resource | A registered resource's value is not valid. | Fix the value that the message names. |
invalid_target | resource is unregistered, disabled, or outside the grant. | Name a resource of the grant. |
invalid_token | The access token is malformed, expired, revoked, or another app's. | Refresh the tokens, or sign in again. |
limit_exceeds_maximum | A headless access key's limit exceeds its token's ceiling. | Lower the limit. |
localhost_not_permitted | The deployment refuses a localhost client ID. | Use a registered client ID. |
logout_not_permitted | The app is disabled, or not registered for logout. | Register the app's post-logout redirect URIs. |
malformed_body | The body is not valid JSON. | Send a JSON object. |
missing_key | The request names no access key, or the zero address. | Send an address or a public key. |
missing_permissions | The request leaves out limits or scopes. | Send both. |
not_configurable | The Tempo Account is not configurable yet. | Upgrade the account, then add the owner. |
origin_required | A request without Origin names an app by its client ID alone. | Send it from the app's page. |
owner_app_taken | Another realm holds the server owner's app. | Give each realm its own app. |
owner_exists | The Tempo Account already holds the owner, or is already configurable. | Use the account as it is. |
owner_unavailable | The user's cloud wallet fails a check to join the Tempo Account. | Upgrade without addOwner. |
passkey_limit | The user holds 10 passkeys, the maximum. | Sign in with one of them. |
passkey_link_expired | The link to a wallet.tempo passkey expired after 5 minutes. | Send the code again without the link. |
passkey_not_permitted | No realm of the request holds passkeys whose relying party covers the page. | Sign in with an emailed code. |
passkey_register_not_permitted | No app at the page's origin holds the tempo-id:sign scope. | Register the passkey on Tempo ID's account page. |
payment_declined | The card issuer or the payment provider declined the payment. | Pay with another card. |
payment_pending | Another request sends the same payment, or the chain has not confirmed it. | Wait, then read the payment. |
payment_reverted | The chain reverted the payment's transfer. | Pay with another token, or to another recipient. |
post_logout_redirect_not_permitted | The URI is none of the app's post-logout redirect URIs. | Use a registered URI. |
public_app | The app has no client secret to rotate. | Name an app with a client secret. |
pushed_authorization_required | The app requires pushed requests, and the URL holds the access key. | Pass par: true to the flow's plugin. |
quote_changed | The payment costs more than the approval page showed. | Request the payment again. |
rate_limited | The request exceeded a rate limit. | Wait for meta.retryAfter seconds. |
realm_exists | A realm with the ID exists. | Choose another ID. |
realm_in_use | An app names the realm. | Remove the realm from each app first. |
recipient_not_permitted | The token's transfer policy refuses the recipient. | Pay with another token, or to another recipient. |
registrar_required | The app may not register third-party apps. | Authenticate as a registrar. |
rejected | Tempo ID refused the authorization request, such as a third-party app's headless request. | Check the request against the app's registration. |
relying_party_taken | Another realm holds the passkeys' relying party. | Give each realm its own relying party. |
resource_exists | Another resource has the identifier. | Choose another identifier. |
scope_without_limit | A scope calls a token that no limit names. | Add a limit for the token. |
session_changed | The signed-in session differs from the one that the approval page showed. | Reload the page. |
session_required | The request has no Tempo ID session, or one older than its max_age. | Sign the user in. |
sign_not_permitted | The page may not sign as the cloud wallet. | Sign from a first-party app's page with tempo-id:sign. |
sign_out_link_expired | A security email's sign-out link is unknown, spent, or older than 7 days. | Sign in on a new browser, which sends a new link. |
signing_key_in_use | A revocation names a signing key that signs tokens. | Send ifSigning: "rotate" with the revocation. |
too_many_signing_keys | 100 signing keys are live, or in their grace period. | Rotate again after the oldest grace period. |
unexpected | Tempo ID failed unexpectedly. | Retry the request. |
unknown_allowance | The connection holds no unexpired allowance for the API. | Authorize the app for the API again. |
unknown_app | No registered OAuth app has the client ID. | Name a registered app. |
unknown_code | The device grant's user code is wrong or expired. | Check the code. |
unknown_endpoint | No route matches the method and the path. | Check both against Tempo ID's OpenAPI document. |
unknown_key | The user holds no live access key with the address on the Tempo Account and the chain. | Name a live access key. |
unknown_order | No MACH order matches the ID and the order token. | Start a new purchase. |
unknown_realm | No realm has the ID. | Name a realm of the deployment. |
unknown_resource | No resource has the identifier. | Name a registered resource. |
unknown_screening | The user has no screening of the address. | Name a screened address. |
unknown_session | The user has no session with the ID. | Read the sessions again. |
unknown_signing_key | No unrevoked signing key has the ID. | Name a live signing key. |
unknown_user | No user has the ID. | Name a user of the deployment. |
unsupported_call | A scope names a call that Tempo ID does not recognize. | Name a recognized call. |
unsupported_token | The token is no supported Tempo token on the chain. | Use a supported token, such as OUSD. |
upgrade_required | The access key's Tempo Account needs an upgrade first. | Upgrade the account, or authorize through a redirect. |
upstream_unavailable | A service that Tempo ID depends on failed. | Retry later. |
webauthn_rejected | A passkey ceremony's challenge is unknown, spent, or expired, or its response does not verify. | Start the passkey sign-in again. |
webauthn_required | A request without a page names a Tempo Account that a passkey owns. | Pass passkey: true from a page, or authorize through a redirect. |