Errors

Basis Theory uses standard HTTP status codes to indicate whether an API request succeeded or failed. A response with a 2xx status code indicates success, a 4xx status code indicates a failure due to information provided with the request, and a 5xx status code indicates an unexpected error occurred within Basis Theory.

In general, errors are returned with a response body that conforms to the RFC 7807 - Problem Details for HTTP APIs specification, as illustrated below.

cURL

{
  "errors": {
    "additionalProp1": ["string"],
    "additionalProp2": ["string"],
    "additionalProp3": ["string"]
  },
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}

Node

try {
    await client.tokens.get(tokenId!);
} catch (err) {
    if (!(err instanceof NotFoundError)) {
        throw err;
    }
    ...
}

JavaScript (legacy)

import { BasisTheory } from '@basis-theory/basis-theory-js';

try {
  const bt = await new BasisTheory().init('<MANAGEMENT_API_KEY>');
  const application = await bt.applications.create({ ... });
} catch (e) {
  console.log(e.status); // HTTP status code
  console.log(e.data); // HTTP Response body
  console.log(e.data.errors);
}

C#

try
{
  await client.Tokens.GetAsync(tokenId);
}
catch (NotFoundError e)
{
  ...
}

Python

try:
    client.tokens.get(id=token_id)
except NotFoundError:
    ...

Go

Response

Attribute	Type	Description
title	string	A short, human-readable summary of the problem
detail	string	A human-readable explanation specific to this occurrence of the problem
errors.{property}	array	An array of human readable error messages returned per request {property}
status	integer	HTTP status code of the response

Error Codes

Error Code	Meaning
400	Invalid request body
401	A missing or invalid BT-API-KEY was provided
403	The provided BT-API-KEY does not have the required permissions
404	Request entity was not found
408	Timed out due to a delayed response from the destination
409	Conflict with the current state of the request entity
422	Request does not satisfy requirements for processing
429	Request has been rate limited
500	Something went wrong on Basis Theory's side

An OpenSSL UNEXPECTED_EOF_WHILE_READING error can occur before the API returns an HTTP response when a client reuses a pooled HTTPS connection that the Basis Theory edge has already closed. See HTTP Client Configuration for recommended pool lifetimes and retry behavior.

Proxy Errors

Failed Proxy requests can be due to several different reasons, such as an error being returned by the proxy destination, an error was thrown from a custom transform, or the proxy request was invalid. For further details about possible proxy errors, or how to return errors from a custom proxy transform, see Proxy Transform Error Handling.

Reactor Errors

Failed Reactors will respond with an error that follows the standard error schema described above. For further details about how to return custom errors or best practices around handling errors within your reactor code, see Reactor Error Handling.