Error Handling

Diagnose Feezback integration errors by checking JWT validity, request payloads, account whitelisting, bank responses, and redirect failure parameters.

Most integration errors fall into one of four categories: JWT signing or structure, invalid product payloads, missing production whitelisting, or downstream bank rejection.

Error handling checklist

When a request fails:

1. Decode the signed JWT and inspect the actual payload.
2. Confirm the JWT was signed with RS512 using the private key that matches the public key registered with Feezback.
3. Confirm iss uses the format tpp/{TPP_ID}.
4. Confirm srv matches the product you are calling.
5. Confirm encrypt: true is present at the JWT top level for /link requests.
6. Confirm flags, when used, are at the JWT top level and not inside flow.
7. Validate the product-specific payload fields.
8. Confirm production creditor accounts are whitelisted when receiving funds.
9. Check whether the bank or ASPSP has a known issue.
10. Escalate to Feezback with the exact timestamp, environment, identifiers, and payload context if the issue persists.

Common error codes

Errors that require Feezback action

Escalate immediately when you hit any of these codes:

1004
1006
1007
1010

Also escalate when:

• You need a production creditor bank account whitelisted.
• You receive 1005 INVALID_JWT but the decoded JWT appears correct.
• A bank rejects a request with 424 ASPSP_ERROR and the request payload passed Feezback validation.
• The documentation does not cover the behavior you are seeing.

JWT errors

JWT errors usually come from signing, claim, or payload placement issues.

Check the signing setup

Check required claims

Check /link JWT structure

For /link requests, include encrypt: true at the top level.

{
  "encrypt": true,
  "iss": "tpp/{TPP_ID}",
  "sub": "user-123",
  "srv": "fast/user",
  "flow": {
    "id": "default"
  }
}

Do not place encrypt inside flow.

Check flags placement

If you send flags, place them at the top level.

{
  "encrypt": true,
  "iss": "tpp/{TPP_ID}",
  "sub": "user-123",
  "srv": "fast/user",
  "flags": {
    "maskAccount": true
  },
  "flow": {
    "id": "default"
  }
}

Do not nest flags inside flow.

A common integration mistake is nesting flags inside flow.

Payment payload errors

INVALID_PAYMENT_PAYLOAD means a field is missing, malformed, or outside the allowed rules for the product.

For FAST Single Payment and Periodic Payment, check:

For Fast Seamless, Request to Pay, and Bulk Payment, check the product-specific request page before resubmitting.

Account whitelist errors

Production payment flows can require creditor accounts to be pre-approved by Feezback.

Do not retry the same request repeatedly until the account is approved.

ASPSP and bank errors

424 ASPSP_ERROR means the request passed Feezback validation but failed at the bank or ASPSP.

Before escalating:

1. Check the live ASPSP issues feed:

   Text

   https://fb.feezback.cloud/aspsp_issues.json

2. Confirm the bank code and account details are correct.

3. Confirm the request was made in the correct environment.

4. Collect the paymentId or paymentRequest, exact timestamp, environment, and context.

5. Send the details to Feezback support.

Redirect failure parameters

Some hosted or redirect flows return a failure reason in the redirect parameters.

Use redirect failure parameters for user-facing recovery flows, but rely on webhooks and API responses for backend status tracking.

Troubleshooting missing webhooks

If the API request succeeded but no webhook arrives:

1. Confirm your endpoint is reachable from the public internet or the expected network path.
2. Confirm you whitelisted all Feezback webhook IPs for the environment.
3. Confirm your endpoint accepts POST requests.
4. Confirm your endpoint returns HTTP 200 within 3 seconds.
5. Search logs by context, paymentRequest, mandateId, or user.

What to include when escalating

Include these details when contacting Feezback:

Related pages