Error Codes

Understand and handle API errors effectively. The API uses standard HTTP status codes and provides detailed error objects in the response body.

Error Response Structure

When a request fails, the API returns a JSON response with a consistent error structure to help you debug. All error responses include `success: false` and a `meta` object.


// Example Error Response (422 Unprocessable Entity)
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "The amount must be at least 50."
    ]
  },
  "error_code": "VALIDATION_ERROR",
  "meta": {
    "timestamp": "2024-07-09T10:00:00.123456Z",
    "version": "v1",
    "service": "transbank-payments"
  }
}

HTTP Status Codes

The API uses the following standard HTTP status codes to indicate the outcome of a request.

Code

Description & Common Cause

200

OK

Standard success response for GET, PUT, or DELETE requests that have completed successfully.

201

Created

The resource was created successfully. Typically returned for POST requests.

400

Bad Request

The request was malformed or invalid. This can be due to invalid JSON, incorrect data types, or other structural issues.

401

Unauthorized

Authentication failed. The API key is missing, invalid, or expired.

403

Forbidden

The authenticated user does not have permission to perform the requested action.

404

Not Found

The requested resource (e.g., a specific transaction or invoice) could not be found.

422

Unprocessable Entity

The request was well-formed, but contains semantic errors. This is the standard response for validation failures (e.g., a required field was missing). Check the `errors` object for details.

429

Too Many Requests

You have exceeded the API rate limit. Implement a backoff strategy and try again later.

500, 503

Server Error

Something went wrong on our end. These are rare. If you receive one, please wait a moment and try again. If the problem persists, contact support.

Internal API Error Codes

In addition to HTTP status codes, the API may provide a specific error_code in the JSON response to help you programmatically handle different failure scenarios.


// Example Error Response (400 Bad Request with an internal error_code)
{
  "success": false,
  "message": "Transbank rejected the transaction: Transaction denied.",
  "error_code": "WEBPAY_ERROR",
  "meta": {
    "timestamp": "2024-07-09T10:05:00.789101Z",
    "version": "v1",
    "service": "transbank-payments"
  }
}

Error Code

Description

VALIDATION_ERROR

One or more parameters in your request were invalid. Check the `errors` object in the response for field-specific messages.

TRANSBANK_ERROR

An error occurred while communicating with Transbank's services. The `message` in the response will contain details from Transbank.

SII_ERROR

An error occurred during an operation with the SII (Chilean IRS), such as generating or sending an invoice.

CERTIFICATE_ERROR

There is an issue with the digital certificate (e-firma) required for SII operations. It might be expired, invalid, or not found.

CAF_ERROR

An issue with the Folio Authorization Code (CAF) file, such as no available folios for the requested document type.

INTERNAL_SERVER_ERROR

A generic, unexpected error occurred on our server. We are likely already notified.

JupiPay