Handling errors in TapTree API

Errors are an inevitable part of working with any API, and understanding how to handle them is crucial. This guide will walk you through the common types of errors and status codes you may encounter when working with the TapTree API, along with best practices for handling them.

Understanding status codes

When interacting with the TapTree API, each response comes with an HTTP status code that indicates the success or failure of the request. The status codes are categorized as follows:

Name
2xx
Description
Indicates successful requests, such as 200 OK, 201 Created, or 204 No Content.
Name
4xx
Description
Client-side errors, implying the issue is on your end. For instance, 400 Bad Request, 401 Unauthorized or 404 Not Found.
Name
5xx
Description
Server-side errors, indicating a problem on TapTree’s end. For instance, 500 Internal Server Error.

Receiving error responses

When you encounter errors while working with the TapTree API, the system provides comprehensive error responses. These responses are structured to help you identify and resolve issues efficiently.

Core attributes

Name
status
Type
string
Description
The HTTP status code associated with the error (e.g., 404 for not found).
Name
type
Type
string
Description
A brief type describing the error (e.g., "Not Found").
Name
detail
Type
string
Description
Detailed information about the error, explaining what went wrong.
Name
links
Type
object
Description
Useful links for additional information, typically pointing to relevant documentation.

Optional attributes

Name
attribute
Type
string | optional
Description
Useful for pinpointing exact problems in your request as it identifies a particular attribute in the request causing the error. This is accompanied by a 422 status code.
Name
allowed_values
Type
string | optional
Description
A list of allowed values for the attribute. For instance, ["eur"] for amount.currency.

404 error response example

{
  "status": 404,
  "type": "Not Found",
  "detail": "No payment exists with token pay_wrong_id.",
  "links": {
    "documentation": {
      "href": "https://docs.taptree.org/errors",
      "type": "text/html"
    }
  }
}

422 error response example

{
  "status": 422,
  "type": "Unprocessable Entity",
  "detail": "The amount is higher than the maximum allowed.",
  "attribute": "amount",
  "links": {
    "documentation": {
      "href": "https://docs.taptree.org/errors",
      "type": "text/html"
    }
  }
}

Before reaching out to support with an error, it's recommended to thoroughly review the error details. Most errors can be resolved by verifying and correcting the request parameters based on the provided information.

Handling different error scenarios

Here are some typical error scenarios and their meaning:

401 Unauthorized: Authentication failed. Verify your API key.
404 Not Found: The requested resource doesn't exist.
422 Unprocessable Entity: Your request has valid data but can't be processed. Check the attribute property for specifics.
429 Too Many Requests: You've hit a rate limit. Try again later.

Successful response example

Successful responses will also be in JSON format. Here's an example of a successful GET request to the /v1/payments endpoint:

Successful response example

{
  "data": [
    // Array of payment objects
  ],
  "has_more": false
}

Complete list of status codes

The TapTree API uses a subset of standard HTTP status codes. Here’s the full list you might encounter:

200 OK: Request successful.
201 Created: Entity successfully created.
204 No Content: Entity successfully canceled/deleted.
400 Bad Request: API cannot understand the request.
401 Unauthorized: Authentication failure.
403 Forbidden: Access to the requested resource is denied.
404 Not Found: Requested resource doesn't exist.
405 Method Not Allowed: HTTP method not applicable for the requested URL.
409 Conflict: Duplicate API call.
410 Gone: Requested object was previously deleted.
415 Unsupported Media Type: Request encoding not supported.
422 Unprocessable Entity: Valid data, but processing issues.
429 Too Many Requests: Rate limit hit. Wait and retry.
500 Internal Server Error: Server error, automatically reported to TapTree.
502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout: Temporary unavailability. Retry later.