Possible errors
Every JSR endpoint on the Payment Manager (lina) wraps two layers of
failure: validations performed by the Payment Manager itself (missing
sub-tenant, unknown enrollment, expired token, malformed payload) and
business errors returned by the account holder (detentora) when the
Payment Manager forwards the call to the Open Finance Brasil Enrollments
API for Payment Initiation (the spec in errors-openapi.yaml). The tables
below list both layers for each endpoint.
Enrollment & device
Create enrollment
POST /api/v1/jsr/enrollments — see Create enrollment.
Proxies POST /enrollments on the Enrollments API.
| HTTP status | Meaning |
|---|---|
400 | Invalid enrollment payload or RP (account holder) configuration. |
403 | Unable to fetch an RP (account holder) access token. |
404 | Sub-tenant or related payment request not found. |
409 | RP returned a conflict. |
424 | RP returned a failed dependency. |
Account holder business codes (surface under 400):
| Code | Meaning |
|---|---|
PERMISSOES_INVALIDAS | The permissions requested for the enrollment don't include PAYMENTS_INITIATE, or include unsupported values. |
CONTA_INVALIDA | The informed debtor account doesn't exist or isn't compatible with the redirectless flow. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
Enrollment device options
POST /api/v1/jsr/enrollments/device/options — see Enrollment device options.
Proxies POST /enrollments/{enrollmentId}/fido-registration-options.
| HTTP status | Meaning |
|---|---|
400 | Invalid callback payload. |
403 | Unable to fetch an RP access token. |
404 | Sub-tenant or enrollment not found. |
424 | RP returned a failed dependency. |
Account holder business codes (surface under 400):
| Code | Meaning |
|---|---|
RP_INVALIDA | The informed Relying Party identifier can't be verified. |
STATUS_VINCULO_INVALIDO | The enrollment status doesn't allow registering a new credential. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
MAXIMO_CHALLENGES_ATINGIDO | FIDO registration parameters were already generated for this enrollmentId. |
Register enrollment device
POST /api/v1/jsr/enrollments/{enrollmentId}/device — see Register enrollment device.
Proxies POST /enrollments/{enrollmentId}/fido-registration.
| HTTP status | Meaning |
|---|---|
400 | Invalid device payload or enrollment metadata. |
403 | Unable to fetch an RP access token. |
404 | Enrollment not found. |
424 | RP returned a failed dependency. |
Account holder business codes (surface under 400). A failed credential
verification here causes the account holder to reject the enrollment
synchronously (a single FIDO2 challenge can't be reused across attempts):
| Code | Meaning |
|---|---|
STATUS_VINCULO_INVALIDO | The enrollment status doesn't allow registering a new credential. |
ORIGEM_FIDO_INVALIDA | response.clientDataJSON.origin can't be verified against the initiator's registered software_origin_uris. |
RP_ID_HASH_INVALIDO | response.attestationObject.authData.rpIdHash can't be verified. |
CHALLENGE_INVALIDO | response.clientDataJSON.challenge doesn't match the value generated by the server. |
PUBLIC_KEY_INVALIDA | The submitted public key is incompatible with the FIDO2 server's requirements. |
EXTENSION_INVALIDA | The extracted extensions are incompatible with the FIDO2 server's security guidelines. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
Get enrollment
GET /api/v1/jsr/enrollments/{enrollmentId} — see Get enrollment.
Proxies GET /enrollments/{enrollmentId}.
| HTTP status | Meaning |
|---|---|
400 | Invalid enrollment metadata. |
403 | Unable to fetch an RP access token. |
404 | Enrollment not found. |
424 | RP returned a failed dependency. |
This is a read-only call — the underlying Enrollments API operation defines
no business (422) error codes for it, only the transport-level responses
above.
Revoke enrollment
PATCH /api/v1/jsr/enrollments/{enrollmentId} (not yet documented as a
standalone guide). Proxies PATCH /enrollments/{enrollmentId} — revokes an
AUTHORISED enrollment or rejects one still awaiting risk signals, account
holder validation, or FIDO enrollment.
| HTTP status | Meaning |
|---|---|
400 | Invalid enrollment metadata. |
403 | Unable to fetch an RP access token. |
404 | Enrollment not found. |
424 | RP returned a failed dependency. |
Account holder business codes (surface under 400):
| Code | Meaning |
|---|---|
STATUS_INVALIDO | The enrollment status doesn't allow cancellation. |
MOTIVO_REJEICAO | Rejecting the enrollment requires an associated rejection reason. |
REJEITADO_OUTRO_SEM_DETALHES | The REJEITADO_OUTRO reason must be accompanied by additionalInformation. |
MOTIVO_REVOGACAO | Revoking the enrollment requires an associated revocation reason. |
REVOGADO_OUTRO_SEM_DETALHES | The REVOGADO_OUTRO reason must be accompanied by additionalInformation. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
Get enrollment user
GET /api/v1/jsr/enrollments/users/{userDocument} (not yet documented as a
standalone guide). Looks up enrollments by user document and deviceId
directly in the Payment Manager's own records — it does not call the
account holder, so there are no business codes to relay.
| HTTP status | Meaning |
|---|---|
400 | Invalid user query. |
403 | Sub-tenant does not belong to the authenticated tenant. |
404 | Sub-tenant or user not found. |
Consent & payment
Create payment consent
POST /api/v1/jsr/consents — see Create payment consent.
Creates the payment consent on the Payment Manager and proxies POST /enrollments/{enrollmentId}/fido-sign-options to obtain the FIDO assertion
challenge.
| HTTP status | Meaning |
|---|---|
400 | Invalid consent payload or enrollment passkey. |
403 | Sub-tenant does not own the resource. |
404 | Sub-tenant or enrollment not found. |
424 | OpenIntegration (account holder) returned a failed dependency. |
Account holder business codes (surface under 400):
| Code | Meaning |
|---|---|
RP_INVALIDA | The informed Relying Party identifier can't be verified. |
STATUS_VINCULO_INVALIDO | The enrollment status doesn't allow signing. |
STATUS_CONSENTIMENTO_INVALIDO | The consent status doesn't allow authorisation. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
PERMISSAO_INVALIDA_VINCULO_CONSENTIMENTO | The permission granted on the enrollment isn't valid for the type of consent informed. |
Authorise payment
POST /api/v1/jsr/payments — see Authorise payment.
Proxies POST /consents/{consentId}/authorise for single/Pix payments, or
POST /recurring-consents/{recurringConsentId}/authorise for Pix Automático
recurring payments — both expose the same business codes below. A 422 on
the account holder side must reject the payment consent, so on the Payment
Manager it always surfaces as 400.
| HTTP status | Meaning |
|---|---|
400 | Invalid authorise payload or payment request state. |
403 | Sub-tenant does not own the resource. |
404 | Payment request or enrollment not found. |
424 | RP returned a failed dependency. |
Account holder business codes (surface under 400):
| Code | Meaning |
|---|---|
STATUS_VINCULO_INVALIDO | The enrollment doesn't have AUTHORISED status. |
STATUS_CONSENTIMENTO_INVALIDO | The payment consent doesn't have AWAITING_AUTHORISATION status. |
ORIGEM_FIDO_INVALIDA | fidoAssertion.response.clientDataJSON.origin can't be verified. |
RISCO | Synchronous risk-signal validation blocked the consent's activation. |
FALTAM_SINAIS_OBRIGATORIOS_DA_PLATAFORMA | The required risk signals for the user's platform weren't fully sent. |
CONTA_DEBITO_DIVERGENTE_CONSENTIMENTO_VINCULO | The debit account informed when the consent was created diverges from the account linked to the device. |
PARAMETRO_NAO_INFORMADO | A required parameter was not informed. |
PARAMETRO_INVALIDO | A parameter doesn't follow the expected formatting rules. |
ERRO_IDEMPOTENCIA | The request body diverges from the content already associated with this x-idempotency-key. |
Participants
Get registered participants
GET /api/v1/open-integration/participants/registered — see Get registered participants.
Lists institutions from the Open Finance directory of participants, not the
Enrollments API — the OpenAPI contract declares only the 200 success
response, with no explicit error responses beyond standard bearer-token
authentication failures.
Get most used participants
GET /api/v1/sub-tenants/{subTenantId}/participants/most-used. Same
directory-of-participants data source as above, scoped to a sub-tenant. The
OpenAPI contract likewise declares only the 200 success response.
Payments & Pix lookups
These three endpoints are outside the redirectless enrollment/consent flow
described by errors-openapi.yaml — they either resolve Pix/DICT data or
read the Payment Manager's own payment records, so their errors are internal
Payment Manager validations rather than relayed Enrollments API codes.
Get Pix details
POST /api/v1/pix/details. Resolves a Pix key or QR Code (static or
dynamic) via DICT.
| HTTP status | Meaning |
|---|---|
400 | Invalid pixKey/qrCode, or a composite/malformed QR Code, or invalid CRC. |
Get payment request
GET /api/v1/payments/requests/{paymentRequestId}.
| HTTP status | Meaning |
|---|---|
403 | Sub-tenant does not belong to the authenticated tenant. |
404 | Payment not found. |
Get payment from holder
GET /api/v1/payments/{paymentId}/external. Consults the payment status
directly at the account holder's Payments Initiation API (not the
Enrollments API) and updates the local record if the status changed.
| HTTP status | Meaning |
|---|---|
400 | Invalid payment state or missing data required to consult the holder. |
401 | Holder returned unauthorized. |
403 | Payment does not belong to the sub-tenant, or a token error occurred. |
404 | Payment not found. |
409 | Holder returned a conflict. |
424 | Holder returned a failed dependency. |
Account holder error code reference
Quick alphabetical lookup across every endpoint that proxies the Enrollments
API. PARAMETRO_NAO_INFORMADO, PARAMETRO_INVALIDO, and ERRO_IDEMPOTENCIA
are common to virtually every write operation and are omitted here for
brevity — see the per-endpoint tables above.
| Code | Meaning | Seen on |
|---|---|---|
CONTA_DEBITO_DIVERGENTE_CONSENTIMENTO_VINCULO | Debit account informed at consent creation diverges from the account linked to the device. | Authorise payment |
CONTA_INVALIDA | Debtor account doesn't exist or isn't compatible with the redirectless flow. | Create enrollment |
CHALLENGE_INVALIDO | FIDO challenge doesn't match the server-generated value. | Register enrollment device |
EXTENSION_INVALIDA | FIDO extensions incompatible with server security guidelines. | Register enrollment device |
FALTAM_SINAIS_OBRIGATORIOS_DA_PLATAFORMA | Required risk signals for the user's platform weren't fully sent. | Authorise payment |
MAXIMO_CHALLENGES_ATINGIDO | FIDO registration parameters already generated for this enrollment. | Enrollment device options |
MOTIVO_REJEICAO | Rejection reason missing. | Revoke enrollment |
MOTIVO_REVOGACAO | Revocation reason missing. | Revoke enrollment |
ORIGEM_FIDO_INVALIDA | FIDO clientDataJSON.origin can't be verified. | Register enrollment device, Authorise payment |
PERMISSAO_INVALIDA_VINCULO_CONSENTIMENTO | Enrollment permission isn't valid for the consent type. | Create payment consent |
PERMISSOES_INVALIDAS | Enrollment permissions don't include PAYMENTS_INITIATE. | Create enrollment |
PUBLIC_KEY_INVALIDA | Submitted FIDO public key is incompatible with the server. | Register enrollment device |
REJEITADO_OUTRO_SEM_DETALHES | REJEITADO_OUTRO reason used without additionalInformation. | Revoke enrollment |
REVOGADO_OUTRO_SEM_DETALHES | REVOGADO_OUTRO reason used without additionalInformation. | Revoke enrollment |
RISCO | Synchronous risk-signal validation blocked consent activation. | Authorise payment |
RP_INVALIDA | Relying Party identifier can't be verified. | Enrollment device options, Create payment consent |
RP_ID_HASH_INVALIDO | FIDO rpIdHash can't be verified. | Register enrollment device |
STATUS_CONSENTIMENTO_INVALIDO | Consent status doesn't allow authorisation. | Create payment consent, Authorise payment |
STATUS_INVALIDO | Enrollment status doesn't allow cancellation. | Revoke enrollment |
STATUS_VINCULO_INVALIDO | Enrollment status doesn't allow the requested operation. | Enrollment device options, Register enrollment device, Create payment consent, Authorise payment |