Most failures can be identified from three things: the HTTP status, the responseCode and the responseMessage. Every row below was seen in this course or comes from the engine’s own error table.
Troubleshooting playbook
| You see | Cause | Fix |
|---|---|---|
404 ENDPOINT_NOT_FOUND_EXCEPTION |
endpointCode typo or wrong environment | Copy the code from Endpoints; codes are case-sensitive |
400 BAD_REQUEST |
Envelope field missing (callerId, requester, payload, applicationNumber for push) | Fix the caller’s body |
500 PARTNER_ERROR_FETCH-<code> + partner JSON |
Partner answered 4xx | Read the partner body: data problem or auth problem? |
500 PARTNER_ERROR_FETCH-<code> + “The service is temporarily unavailable…” |
Partner 5xx, timeout, DNS or TLS on a fetch | Check the trace; contact the partner; check the URL |
500 PARTNER_ERROR_PUSH-<code>-<appNo> |
Partner error on push (raw message shown) | Fix, then Resubmit |
500, responseCode null, message TOKEN_EXTRACTION_ERROR |
Login worked but extractPath is wrong | Compare extractPath with the login response logged in Kibana (the trace does not list login calls) |
500, message TOKEN_EXPIRY_EXTRACTION_ERROR |
expiryBuffer missing or not a number | Add "expiryBuffer": 300 |
500, message MISSING_ENVIRONMENT_VARIABLE |
A "${NAME}" value is not defined on this environment (or the name is misspelt) |
Check the exact name; ask the platform team to define it (Lesson 6.3) |
500, message Invalid JSONata expression |
Mapping syntax error at runtime | Fix the mapping; run the mapping test |
| 500 NullPointerException | failureCondition without errorMapping, or no tokenConfig | Add the missing block |
| 400/404 with your code | Your failureCondition fired (working as designed) | Nothing, or adjust the condition |
500 ATTACHMENT_MISSING_REQUIRED_FIELD_ERROR |
A FIELD.* key or applicationId missing | Check the original payload |
| Mock: “Request was not matched” table | Mock server reloading, or no rule and no Otherwise matched | Retry after a few seconds; then check rule conditions |
Save fails: INVALID_JSONATA_EXPRESSION |
Syntax error, or no literal key (save-time check uses a dummy payload) | Keep "method"; credentials literal or ${ENV} |
Save fails: 400 BAD_REQUEST on URL |
URL contains %, $, ~, @, : or spaces in the path |
Use {placeholders} and query parameters |
For any ticket, in this order:
Get the status, responseCode and responseMessage (from the caller or from Requests).
Caller problem (404/400 envelope), engine/mapping problem (TOKEN_*, JSONata, NPE), or partner problem (PARTNER_ERROR).
Compare what was sent with the partner contract: URL, headers, body. No Request, or no partner call? Open Kibana and read the engine log for that call (Lesson 6.3).
Mapping test for the request pass; a mock rule for the partner side.
Fix, re-run the curl, Resubmit pushes, and write down the signature and fix for the team.
A push returns 500 PARTNER_ERROR_PUSH-VICTOR_KEZA_DOCUMENT_PUSH-C26… with message {"code":"DOCUMENT_REQUIRED"}. Where is the bug most likely?
D. The partner rejected the body because document.url is missing. Check the marker and the CERTIFICATE.* keys in the original payload.
Fetch calls to a slow partner return the generic “The service is temporarily unavailable” after exactly 60 seconds. What is happening?
D. The default response timeout is 60 s (connect 10 s). Per-endpoint timeouts (1–120 s) exist but have no portal field: ask the platform team.
Your turn · collect three signatures
Break your own calls on purpose, one at a time, and classify each with the routine above:
- Send your endpoint code in lower case (for example
aline_keza_eligibility_fetch).- Remove
callerIdfrom your curl body.- On
${YOUR_FIRST_NAME}_KEZA_ELIGIBILITY_FETCH, setextractPathtodata.toknand the storageKey to${YOUR_FIRST_NAME}_KEZA_TOKEN_62, so a fresh login happens.Done when: you have recorded 404 ENDPOINT_NOT_FOUND_EXCEPTION, 400 BAD_REQUEST and 500 TOKEN_EXTRACTION_ERROR, each with the caller/engine/partner class. Restore extractPath and the storageKey.
← 6.1 Read requests and traces · 6.3 Debug endpoints with Kibana logs →