Error Responses

All Trancent APIs return structured errors following RFC 9457 Problem Details for HTTP APIs.

Format

Every error response has Content-Type: application/problem+json and a body with these fields:

Field	Type	Description
`type`	string	URI identifying the problem type. Currently `about:blank` for all errors.
`title`	string	Short, human-readable summary of the HTTP status (e.g. `Bad Request`).
`status`	integer	HTTP status code repeated in the body.
`detail`	string	Human-readable explanation specific to this occurrence.
`errorCode`	string?	Machine-readable error code for domain validation errors (extension member).

Example

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "functionalAmount values do not sum to zero",
  "errorCode": "VALIDATION_ERROR"
}

Common status codes

400 Bad Request

The request body is invalid, required fields are missing, or domain validation failed (e.g. unbalanced entry, zero amounts). Check the detail and errorCode fields.

401 Unauthorized

Missing or invalid authentication. For the Service API: missing/invalid API key, missing signature headers, or request timestamp out of the ±5 minute window.

403 Forbidden

Authenticated but not authorized. Common causes: not a member of the organization, insufficient role (e.g. suspend requires admin/owner), or the ledger is suspended.

404 Not Found

The requested resource does not exist, or belongs to a different tenant (returned as 404 to prevent information leakage).

409 Conflict

A duplicate externalId was detected. The entry already exists — this is safe to ignore if you are retrying. The original entry was not modified.

500 Internal Server Error

Unexpected server error. Retry with exponential back-off. If the error persists, contact support.

503 Service Unavailable

The ledger service is temporarily unavailable. Retry with exponential back-off.

Domain error codes

When the API returns a 400 or 409 due to a domain rule violation, the errorCode extension field identifies the specific rule:

errorCode	Meaning
`VALIDATION_ERROR`	Entry fails a financial rule (e.g. unbalanced amounts, zero-amount line).
`DUPLICATE_ENTRY`	An entry with this `externalId` already exists (409).
`REVERSAL_NOT_FOUND`	The target entry for reversal was not found.
`ALREADY_REVERSED`	The entry has already been reversed.
`CANNOT_REVERSE_REVERSAL`	You cannot reverse a reversal entry.
`PERMISSION_DENIED`	The authenticated user lacks permission for this operation.
`DATABASE_ERROR`	Unexpected persistence failure.