Skip to content
LogoLogo

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.

Read a refusalDemo

Walkthrough

Create the instance

tempo.config.ts
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 
  }
}

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
  }
}

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
  }
}

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.') 
  }
}

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
  }
}

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.

main.ts
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.

main.ts
import { Accounts } from 'accounts'
 
export function wait(error: Accounts.RequestError) {
  if (error.reason !== 'rate_limited') return undefined
  return Number(error.meta?.retryAfter ?? 60) 
}

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.

main.ts
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
  }
}

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>
  )
}

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
  }
}

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
  }
}

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()
}

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.

ReasonFaultFix
access_key_changingAnother request changes the same limit or the scopes.Retry after it ends.
access_key_endpoint_failedAn API's access key endpoint failed at the approval.Approve again.
access_key_pendingThe access key has an unregistered key authorization with other limits or scopes.Request a new access key.
access_key_takenAnother app holds the access key for the Tempo Account.Request a new access key.
allowance_redeemedThe API redeemed the connection's allowance for another access key.Use the access key of meta.address.
already_decidedThe user already approved or denied the device code.Request a new code.
app_existsAnother OAuth app has the client ID.Choose another client ID.
authorization_expiredThe authorization request that a Tempo ID page continues is forged or expired.Start the sign-in again.
backend_sign_in_not_permittedThe app has no client secret or keys, or no backend sign-in.Sign in through a redirect.
body_too_largeThe body exceeds 65,536 bytes, or a pushed request 8,192 bytes.Send a smaller body.
challenge_not_permittedA headless request holds a challenge without the tempo-id:sign scope.Send the challenge through a redirect.
config_conflictThe chain's account configuration differs from Tempo ID's.Read the account again.
configurable_accounts_disabledThe deployment has no configurable accounts on the chain.Select a chain of meta.configured.
connection_mismatchA redemption's nonce or public key does not match the prepared access key.Send the newest nonce and its public key.
consent_requiredA redirect requests an access key with prompt=none, which shows no approval page.Remove prompt=none.
cross_site_requestA form, or a write without a body, came from another site.Send JSON from an allowed origin.
duplicate_limitTwo limits name one token.Limit each token once.
duplicate_scopeTwo scopes name one call on one target.Name each call once.
embed_not_permittedA native or device app frames the embedded sign-in.Sign in through a redirect.
employee_requiredAn employee app's request holds no active employee identity.Send an admitted request's identity assertion.
empty_limitslimits is empty.Name a token.
empty_scopesscopes is empty.Name a call.
expiry_exceeds_maximumA headless access key lasts longer than a year.Use an earlier expiry.
expiry_passedThe expiry is in the past.Use a future time, or a duration.
foreign_accountThe user holds no such Tempo Account in the app's realms.Name one of the user's Tempo Accounts.
funding_unavailableThe deployment sells no MACH.Choose another deposit method.
google_unavailableThe deployment offers no Google sign-in.Sign in with an emailed code or a passkey.
insufficient_balanceThe Tempo Account cannot pay the network fee to revoke or change an access key.Add funds.
invalid_access_key_endpointAn access key endpoint is not an https URL on its resource's origin.Register such a URL.
invalid_appAn OAuth app value is not valid.Fix the value that the message names.
invalid_chainThe chain ID is 0.Use a Tempo chain ID.
invalid_clientThe app is unknown or disabled, or its credentials are missing or wrong.Send an enabled app's credentials.
invalid_client_attestationA native app's client attestation is missing, or does not verify.Attest the instance key again.
invalid_client_metadataA dynamic client registration names a value that Tempo ID refuses.Leave out the value that field names.
invalid_codeThe emailed code is wrong, expired, or used.Request a new code.
invalid_dpop_proofA DPoP proof is missing, invalid, or replayed.Send a new proof, or sign in again.
invalid_expiryThe expiry is 0, not a whole number of seconds, or in milliseconds.Use a future time in whole seconds, or a duration.
invalid_fieldA request field is missing or malformed.Fix the field that field names.
invalid_id_token_hintA logout's hint is not an ID token that Tempo ID signed for the app.Send the app's ID token.
invalid_originA headless request came from an origin that the app does not allow.Call from a page on the app's origin.
invalid_periodA limit's period is not a whole number of seconds.Use whole seconds, a duration, or 0 for a one-time limit.
invalid_public_keyThe public key is not a valid point.Send an uncompressed public key, or an address.
invalid_realmA realm value is not valid.Fix the value that the message names.
invalid_recipientsA scope names the zero address, one address twice, or recipients on a call that takes none.Name each recipient once.
invalid_redirect_uriA dynamic client registration names no redirect URI, more than 10, or one that Tempo ID refuses.Name a public https URI.
invalid_resourceA registered resource's value is not valid.Fix the value that the message names.
invalid_targetresource is unregistered, disabled, or outside the grant.Name a resource of the grant.
invalid_tokenThe access token is malformed, expired, revoked, or another app's.Refresh the tokens, or sign in again.
limit_exceeds_maximumA headless access key's limit exceeds its token's ceiling.Lower the limit.
localhost_not_permittedThe deployment refuses a localhost client ID.Use a registered client ID.
logout_not_permittedThe app is disabled, or not registered for logout.Register the app's post-logout redirect URIs.
malformed_bodyThe body is not valid JSON.Send a JSON object.
missing_keyThe request names no access key, or the zero address.Send an address or a public key.
missing_permissionsThe request leaves out limits or scopes.Send both.
not_configurableThe Tempo Account is not configurable yet.Upgrade the account, then add the owner.
origin_requiredA request without Origin names an app by its client ID alone.Send it from the app's page.
owner_app_takenAnother realm holds the server owner's app.Give each realm its own app.
owner_existsThe Tempo Account already holds the owner, or is already configurable.Use the account as it is.
owner_unavailableThe user's cloud wallet fails a check to join the Tempo Account.Upgrade without addOwner.
passkey_limitThe user holds 10 passkeys, the maximum.Sign in with one of them.
passkey_link_expiredThe link to a wallet.tempo passkey expired after 5 minutes.Send the code again without the link.
passkey_not_permittedNo realm of the request holds passkeys whose relying party covers the page.Sign in with an emailed code.
passkey_register_not_permittedNo app at the page's origin holds the tempo-id:sign scope.Register the passkey on Tempo ID's account page.
payment_declinedThe card issuer or the payment provider declined the payment.Pay with another card.
payment_pendingAnother request sends the same payment, or the chain has not confirmed it.Wait, then read the payment.
payment_revertedThe chain reverted the payment's transfer.Pay with another token, or to another recipient.
post_logout_redirect_not_permittedThe URI is none of the app's post-logout redirect URIs.Use a registered URI.
public_appThe app has no client secret to rotate.Name an app with a client secret.
pushed_authorization_requiredThe app requires pushed requests, and the URL holds the access key.Pass par: true to the flow's plugin.
quote_changedThe payment costs more than the approval page showed.Request the payment again.
rate_limitedThe request exceeded a rate limit.Wait for meta.retryAfter seconds.
realm_existsA realm with the ID exists.Choose another ID.
realm_in_useAn app names the realm.Remove the realm from each app first.
recipient_not_permittedThe token's transfer policy refuses the recipient.Pay with another token, or to another recipient.
registrar_requiredThe app may not register third-party apps.Authenticate as a registrar.
rejectedTempo ID refused the authorization request, such as a third-party app's headless request.Check the request against the app's registration.
relying_party_takenAnother realm holds the passkeys' relying party.Give each realm its own relying party.
resource_existsAnother resource has the identifier.Choose another identifier.
scope_without_limitA scope calls a token that no limit names.Add a limit for the token.
session_changedThe signed-in session differs from the one that the approval page showed.Reload the page.
session_requiredThe request has no Tempo ID session, or one older than its max_age.Sign the user in.
sign_not_permittedThe page may not sign as the cloud wallet.Sign from a first-party app's page with tempo-id:sign.
sign_out_link_expiredA 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_useA revocation names a signing key that signs tokens.Send ifSigning: "rotate" with the revocation.
too_many_signing_keys100 signing keys are live, or in their grace period.Rotate again after the oldest grace period.
unexpectedTempo ID failed unexpectedly.Retry the request.
unknown_allowanceThe connection holds no unexpired allowance for the API.Authorize the app for the API again.
unknown_appNo registered OAuth app has the client ID.Name a registered app.
unknown_codeThe device grant's user code is wrong or expired.Check the code.
unknown_endpointNo route matches the method and the path.Check both against Tempo ID's OpenAPI document.
unknown_keyThe user holds no live access key with the address on the Tempo Account and the chain.Name a live access key.
unknown_orderNo MACH order matches the ID and the order token.Start a new purchase.
unknown_realmNo realm has the ID.Name a realm of the deployment.
unknown_resourceNo resource has the identifier.Name a registered resource.
unknown_screeningThe user has no screening of the address.Name a screened address.
unknown_sessionThe user has no session with the ID.Read the sessions again.
unknown_signing_keyNo unrevoked signing key has the ID.Name a live signing key.
unknown_userNo user has the ID.Name a user of the deployment.
unsupported_callA scope names a call that Tempo ID does not recognize.Name a recognized call.
unsupported_tokenThe token is no supported Tempo token on the chain.Use a supported token, such as OUSD.
upgrade_requiredThe access key's Tempo Account needs an upgrade first.Upgrade the account, or authorize through a redirect.
upstream_unavailableA service that Tempo ID depends on failed.Retry later.
webauthn_rejectedA passkey ceremony's challenge is unknown, spent, or expired, or its response does not verify.Start the passkey sign-in again.
webauthn_requiredA request without a page names a Tempo Account that a passkey owns.Pass passkey: true from a page, or authorize through a redirect.

Next steps