Skip to main content


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.

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


titlestringA short, human-readable summary of the problem
detailstringA human-readable explanation specific to this occurrence of the problem
errors.{property}arrayAn array of human readable error messages returned per request {property}
statusintegerHTTP status code of the response

Error Codes

Error CodeMeaning
400Invalid request body
401A missing or invalid BT-API-KEY was provided
403The provided BT-API-KEY does not have the required permissions
404Request entity was not found
422Request does not satisfy requirements for processing
429Request has been rate limited
500Something 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.