Error handling

All API errors have the same shape, regardless of the resource or the endpoint. This makes your integration predictable: you parse the error response once and reuse it across the entire API.

Uniform structure

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed: amount must be a positive amount in pesos (e.g. 1500.50).",
    "details": [
      { "field": "amount", "issue": "amount must be a positive amount in pesos (e.g. 1500.50)." }
    ]
  },
  "requestId": "req_3f8a1c9e2b"
}

string

Stable, machine-readable code. Use it to branch your error-handling logic (do not parse the message).

string

Human-readable message. It may change over time: do not use it to make decisions in your code.

array

Present in validation errors. A list of { field, issue } that indicates which field failed and why. In the batch mode of POST /v2/debts each entry also carries the index and externalRequestId of the failing item. Malformed JSON returns [{ "field": "body", "issue": "Invalid JSON syntax" }].

string

Unique identifier of the request. Share it with support to trace exactly what happened.

Catalog of codes

HTTP	Code	When it occurs
`207`	`PARTIAL_UPDATE`	Only in `PATCH /subscriptions/{id}`: the subscription was updated, but updating one of its already generated debts failed. The `message` says how many. See Subscriptions.
`400`	`INVALID_REQUEST`	The payload or the filters did not pass validation: a missing, invalid, or not allowed field, a wrong type (for example `"true"` in a boolean), `autopay` together with `paymentMethods`, a malformed date, malformed JSON, etc.
`400`	`BAD_REQUEST`	Your client has several companies and you did not send `companyCode`. See API conventions.
`404`	`RESOURCE_NOT_FOUND`	The referenced resource (debt, product, contact, route) does not exist.
`409`	`RESOURCE_CONFLICT`	The external key already exists: a repeated `Idempotency-Key`/`externalRequestId`, a duplicate `externalSubscriptionId` or `externalPaymentLinkId`, an `externalProductId` or product name already in use. See Idempotency.
`422`	`RESOLUTION_ERROR`	TapiPay could not resolve your configuration: the `companyCode` you sent is not a company of your client, or the organization is not properly configured (for example, it is missing active modalities).
`422`	`BUSINESS_RULE_VIOLATION`	The action is not allowed by the state of the resource or a business rule: updating a debt that is not in `PENDING`, canceling a debt twice, modifying a `CANCELLED` or `ENDED` subscription, an `externalClientId` that does not match a contact, etc.
`429`	`RATE_LIMITED`	Too many requests in a short time. Retry with backoff.
`500`	`INTERNAL_ERROR`	Unexpected server failure. Not attributable to your request.

RESOLUTION_ERROR without companyCode indicates that the organization associated with your token is not properly configured in the system. If you see it persistently, contact support with the requestId.

API Gateway errors (`401` and `403`)

401 and 403 are issued by the API Gateway, before the request reaches the API, and do not use the uniform structure: they carry no error object and no requestId.

HTTP	When it occurs	Body
`401`	The token in `x-authorization-token` is missing, invalid, or expired.	`{"message": "Unauthorized"}`
`403`	The `x-api-key` is missing or invalid.	`{"message": "Forbidden"}`
`403`	The token is valid but has no permission on the resource.	`{"Message": "User is not authorized to access this resource with an explicit deny"}`

In the permission 403 the field is capitalized (Message). If your code reads the error, handle both shapes: the API’s error envelope and the gateway’s plain object. More detail in Authentication.

The `message` is informational

The text of error.message is useful for debugging, but it is not a contract: it can change without notice. To decide what to do, use error.code and, on validation errors, error.details[].field. The message examples in these guides are illustrative.

Recommendations

Branch by code

Decide your logic with error.code, never with the text of message.

Save the requestId

Log the requestId in your logs: it is the fastest way for support to trace a request.

Retry with idempotency

On 429 or 500, retry with the same Idempotency-Key to avoid duplicates.

Validate before sending

Use error.details to show your users which field to fix on 400 errors.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Uniform structure

Catalog of codes

API Gateway errors (`401` and `403`)

The `message` is informational

Recommendations

Branch by code

Save the requestId

Retry with idempotency

Validate before sending

​Uniform structure

​Catalog of codes

​API Gateway errors (401 and 403)

​The message is informational

​Recommendations

Branch by code

Save the requestId

Retry with idempotency

Validate before sending

Uniform structure

Catalog of codes

API Gateway errors (`401` and `403`)

The `message` is informational

Recommendations