Error handling

All Facade 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.

string

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

Catalog of codes

HTTP	Code	When it occurs
`400`	`INVALID_REQUEST`	The payload did not pass validation: a missing or invalid field, `autopay` together with `paymentMethods`, a malformed date, etc.
`401`	`AUTHENTICATION_FAILED`	The TAPI token is missing, invalid, or expired. See Authentication.
`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`. See Idempotency.
`422`	`RESOLUTION_ERROR`	TapiPay could not resolve your internal configuration (organization or modalities). This is a configuration problem on the system side, not in your request.
`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 an already-paid debt, paying an expired payment link, 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.
`502`	`SQS_PUBLISH_ERROR`	A temporary failure while queuing the internal processing of a charge. Retry with your `Idempotency-Key` so as not to duplicate.

RESOLUTION_ERROR indicates that the organization associated with your token is not properly configured in the system (for example, it is missing active modalities). If you see it persistently, contact support with the requestId.

The 401 can arrive in two shapes. If the failure happens at the API Gateway (a missing or invalid x-api-key or token), the response is {"message":"Unauthorized"}, without the error object. If the request passes the gateway but the Facade rejects authentication, it uses the standard shape with error.code: AUTHENTICATION_FAILED.

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, 500, or 502, 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

Concepts

Resources

Payment portal

Webhooks

Uniform structure

Catalog of codes

Recommendations

Branch by code

Save the requestId

Retry with idempotency

Validate before sending

​Uniform structure

​Catalog of codes

​Recommendations

Branch by code

Save the requestId

Retry with idempotency

Validate before sending

Uniform structure

Catalog of codes

Recommendations