Errors

Overview

The Tight API employs conventional HTTP response codes to indicate the success or failure of an API request. See the table below for a summary of status codes the Tight API uses:

HTTP Status Codes


200	OK	Everything worked as expected.
207	Multi-status	Partial success, some aspects of the request failed.
400	Bad Request	The request was unacceptable, often due to validation error.
401	Unauthorized	The `access_token` provided is invalid.
403	Forbidden	The `access_token` doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request hit constraints due to concurrent requests. Please try again.
429	Too Many Requests	The rate limit was hit, see Rate Limits for more details.
500, 503, 504	Server Errors	Something went wrong on Tight’s end. (These are rare.)

Error Responses

In addition to the HTTP response codes, the Tight API has a unified error schema on all error responses.

enum<string>

The type of the error. Safe for programmatic use.Available options: UNKNOWN_ERROR, EXPIRED_TOKEN, INVALID_TOKEN, BAD_REQUEST, JSON_ERROR, DUPLICATE, REQUIRED, INVALID_VALUE, NOT_MODIFIABLE, INVALID_FORMAT

string

A human-readable message providing more details about the error.

string

If the error is parameter-specific, the parameter related to the error. This can be used to display a message near the correct form field.

Validations

All operations in the Tight API include an array of error objects so that the API consumer receives all possible errors with a given request. For example, if attempting to save a bank transaction without its amount and with an invalid bank account, the following error response would be returned:

{
    "result": "FAILURE",
    "data": null,
    "error": [
        {
            "type": "REQUIRED",
            "message": "Amount is required",
            "param": "amount"
        },
        {
            "type": "INVALID_VALUE",
            "message": "The bank account provided is not valid",
            "param": "bankAccountId"
        }
    ]
}

The Tight API is designed to provide user-facing error messages and field-level validation out of the box. As an additional best practice, log and monitor errors for troubleshooting and analytics.

Retrying and Escalating

For server errors (500, 503, 504), retry the request with exponential backoff. If errors persist, escalate to the Tight API team. For rate limiting errors (429), see the Rate Limits documentation for guidance on handling retries and backoff.

Patterns

Reference

Overview

HTTP Status Codes

Error Responses

Validations

Retrying and Escalating

​Overview

​HTTP Status Codes

​Error Responses

​Validations

​Retrying and Escalating

Overview

HTTP Status Codes

Error Responses

Validations

Retrying and Escalating