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

JavaScript

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#

using BasisTheory.net.Common.Errors;
using BasisTheory.net.Tokens;

try {
  var client = new TokenClient("<API_KEY>");
  var token = await client.CreateAsync(new Token {...});
}
catch (BasisTheoryException btex) {
  Console.WriteLine(btex.Message);
  Console.WriteLine(btex.Error.Status); // HTTP status code
  Console.WriteLine(btex.Error.Title);  // error title from HTTP response
  Console.WriteLine(btex.Error.Detail); // error detail from HTTP response

  // (optionally) btex.Error.Errors contains Dictionary of validation errors
}

Python

import basistheory
from basistheory.api import tokens_api
from basistheory.model.create_token_request import CreateTokenRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    try:
        token = token_client.create(create_token_request=CreateTokenRequest(...))
    except basistheory.ApiException as e:
        print("Exception when calling TokensApi: %s\n" % e)

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  createTokenRequest := *basistheory.NewCreateTokenRequest("Sensitive Value")
  ...

  createTokenResponse, createTokenHttpResponse, createErr := apiClient.TokensApi.Create(contextWithAPIKey).CreateTokenRequest(createTokenRequest).Execute()

  if createErr != nil {
    fmt.Printlnf("Create token request failed: %v", createErr)
  }
}

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

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 Errors.

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 of reactor errors, or best practices around handling errors within your reactor code, see Reactor Errors.