> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/customs-catalog-api/customs-catalog-api/error-handling/retry-strategy-and-checklist.md).

# Retry Strategy and Checklist

{% @code-walkthrough/html-renderer aspectRatio="1.5" htmlZ0="H4sIAAAAAAAAA81bS48kN3K-z6-IzZF3qjSV2VnV1a-qrtaORjNQA\_MQZkZrDwQBYmZGVnE7i8wlWd1dajSgk64G1rIPi7344rvhgwEffPBPmV9ikMwH81GtHkH2bg8wlZVBBiM-RgQjSNbpb754\_fTd-6-ewUqts7MHp\_oDMsKWCw-Zp18gSc4eAJyuURGIV0RIVAvv63fP\_WMP9moSI2tceJcUr3IulAcxZwqZWnhXNFGrRYKXNEbffBkBZVRRkvkyJhkuxkFYslJUZXj25KtzeCYEF\_AFxlRSzuCdQDzds2TdMKPsAgRmCy8XGHPGMFYerASmC2-lVC5ne3spZ0oGS86XGZKcyiDm63Kgj-gvFVE0tp1jwaXkgi4pcxn9\_Lh7sZSTz1Kyptl2cf75y8dfZXj9-CVnfHa1XKnfTcNwfhCG88Mw\_G3R6i0XpEOcH4XhbxMq84xsF\_KK5J7VQqpthnKFqEoNzRv9BPDpCD6dzSJMuUDzSFKFAm4g4te-pN9TtpxBxEWCwo\_49RzWRCwpm0E4h5wkiaGHc7h9YNjNBOcKbswzgO9HyxlUfw\_T45Sk8byixkQkVZOHqfmrqQm9pAmKgooTPE7DmrreKExK5g9PpmQ\_Oq6pGYkwq6iH06PpcVRTteUawQ01TMdHE1JT5SZSeK1m\_X21gn7CLfnhGCcn-w5VCUQ\_oww1-WEcJQc4dvTljO2mEiH4VSVzp-8KLwVns359DZKi0KmDlaGu-KUBs8tZU3mOrFeqBBWhmR8lpm86Tg\_Sk1bfEq0OGiRWlLOC3kCyMJffrTGhBAa5wBSF9GOeceHLeIVrnEFCxMWwMqamaXWNa2L-5g69aV6TaBJPYpfeNLDJ0cQxg66JHUwOJgeRS28aGRmTMWn0b5pZSvQ\_l940tKPx0fioQW-aWpd\_09j20\_10etjQv2FuXXrT4Lr6NU2uh94wui5-TbPrka9heF3-TdPbwb8yPpziFI8a-jXMr4nfrWuGemkbQcSTbWVfK6TLlZrBOAz\_ruyjNUkzDdmKJgmy8n1E4oul4BuWzOCSiIG2zGFJbJp0prkawy7pekXwbVifwSMd2B-NQBImfYmCpg132fsUXm90eL4SJM9RQEqzTIJaIdBUkDWOQMaC63eUKRSMZNkWaAoMMcEEPt17YE0pz--lqL-dAdko3nl\_3YagWgrGweRA4Lr-FLguG1nZIiLsWj8DxhnOtVbPqcCUX5cC3lZizmb-FUYXVPlVZ7iBYpErGdxqFk9Xgq9x7y1JiaCakeERrDnjcNNC-fzzl6AXWdCL7KMR6EYyJ7HmZbvpFIVQZlbCQlgDEKzJdSn94TTM3QXRQuXM1Yeffvjw0w\_wJZIERfmtUDHALUaCX1XzUOmUZnhdIkYyumQ-VbiWM4hRz2lJWpJ8BmFw6OBrJfEjrhRfa-J-RbxtDGpcohr5vti4zSX9HtvDG8JVYU46JyneZ6gUCl8zsdlCMJ7UvbQovhKEyZSL9Qw22rBjIrHhQKVjmZBc-dbViio0jFHbgvaKXnV1DISb2tT1tGmYZzCe93hvsS4Mq7lcjZtgWe3HDr4t7Y9q7RviFyvCcBc0fhiEkzsmdHzgjKi18iudgklDdb226Iy4tP1ywo4Mh6ZUxTo0nHcHLJp3bPoFLpElbZvO7NubljGb\_309OzMTueal8e4X7FvDjosxDc-cZtmvYqoHB7tm6\_BOW6071fluMD7WwS0MXJ5FlixIQjdyBicnJyf5dZNobA8kz2jSmC2tpC8wAYCbcm4eRifjeBw3DfRhijjBybwcrGybYkxi0gDNJ-vIxK-yzclkGobY4Zfux0ddfgkeHrf4yYttQ75w\_\_CEtBzoIYbpJMUOv4jgYZqU\_D4m7auwGblqjRyZbpoSFHlCW4Ii\_Sgk2IV5eqzTsHarNpJpFKWTabtVG5\_94yhJj-fNVKN2oTc6nWU8wbYXmbTPEP4v14Yj13QLy\_YzTJUmTtoLR5mKViIVa2BzkDIYNd\_e7Red6FsONaz7X\_tyRRKdeIXGgfbzaxDLiAzCkfkXTKrGJtTIlaDsQtelHR1Mzl4GRTcANIPF8aQbJqvg3Ru2x71xUu9NtOdXp-0VjjmXVGepM12rE0UvsX9O3Dyq1xyM4gkVGFt2Mc82a9ayiE5CoGUpy\_9KpmJ\_ZgaPHs07YpJI8myjsI6YxmTmoHhuPisTmzdNZXLXpFelzHCH1YzL3h2IX\_W4kPWePnCB60lT22LTomodXFJJI7NeEkbXxHbTlHOmgTuQEG8iGvsRfk9RDMJgfDgaj8JgfzQeap1XVXC7wK1JxmXZvVq9BF\_DTUMCJ\_ExjxlR-A8Dfxzm18M6vihuAkvVcbyrYzhshZug2L\_iosfi-qfSt8uvmc5x4NpdmQgbuptM7ZzWqgId1oZkKhMfL5EpWWTw\_RP7lIhOhqFLvnv4jpuyu3mmiZkzo-gOO2uGLmfFN-lDO27GGyF1gCi02rnYl3CUBfPwDsjspsUd0W\_Sjn7hQdXa2EIBirsA6pguRw4z86K3BqVshYKqRpjQQs1MJW92Bt2F1ZHaNBjO3U6BLu\_hrk66wXDeUlMH-HFXz6PhL8ogakFu7jXOtONFJNYLrG-qz4-MiMe62Chj4nHtLIWJ7rdTxB3rpBM0eqa6oDqT2p04R4lRZ4IaGjYCTcFIV-1lstRM-NLpdDpttCvTpWaieXCCYdRoVyZMjXYhkgM86VlKTTjQFXNPSPBNJd0uO\_oypHIltIVHpzApJzwiyRJ\_lbLj6B5VhxNmwiLMTHcnUGGj7uxWLG4FuaPsuDNPMrp3MuMknhxODrvVwyT92WrEMmwn0cnJ0VHYYZimEUY\_V45Yhp16ZHI8NaVMg2GYnqTpr1mPVPCMGpqNXLF-YUnSj3ynJunHs1OU9KPUW5VYJ7K5cTs5Pugmx93cuNqKbYZ\_u8UMnU2ILgPTsN3ZpLLtzj2jOxu9Q2dnZ01ZuVdXn1AFiiz\_BvcTJj\_r9vfaT6gKPbsI" htmlZ1="uZu3d3i8Istfc\_dBs\_sVNx80u7\_S3kMBzMjRaVQL9Au9vA\_tjo\_3Ydjx8D5kdvi3Pcrp28ZsLlFNr7a9quyyWl8pM5uPUcbji758pKpOmmnmbgssRiqzNKe6EVwRhYPxcZjgctiTF3xhTonaWYE9O6r0LbzC1qhB39ZHD6mYSFsJtVL5-myqi45blvdsxTTSEouJIqIqSJzy0w5iCtDJz9efDp5ODVrx-Mgq9P3An\_6SIvR9owh15sKncdsAf2HkPdm9Cz7vmW-nQr3DArV0HbdsJbemTccrm4mtadMJV1VS-9EhqFeuTrjol6wdL3plawcMd8rsOVErWhSb9q3jh4ODOxfljts-51x1T8VS-7bfbXu3LPtodzpuebhzl9fesbf6h41UNN361SaZsVM\_QnWF5XnorauMz7jCjzmC7B6w9Z6B9WX-B87BScKV7NZE7kag0xLqc84iCXE2c-33\_nTE4dFfHzZN1bTrrw8bxmra9daHrrme7hU3mU737GW0U32Gb644JfQSaLLwSJ579qaTeRVnRMqFVx3vemcPinl1ycW5YdHRUGVOWItsvUNPnHdmr6R9SViSUbY83dPNnd5d3mZXzDs73UvoZdmw-WW1f9a64rbar4h5ya485\_POnmY0vgDCtoBGmFjvgSoOEhEEKrGF5YYmhMUIhCWwKmQtFojgdC\_vxcKe6e2CwpzOVScpFotXr-HNs3dv3ndQ6O9orcF2Nf3g9aunz-7ZWZuI07XZq8CzR6nqiMXrn6TyDKI1QS0x6gMFz7mX-AZjpJeY3FcWvfXtGVs1T2e7W9p4smsq3GhjITlyLEHC\_\_wnWBNRHPA6Jyy5y0x19HBGao2lI0bh8VrgJpsdbc0837u1vNh22\_Z5y4MGoX55KmNBc2Vbx5xJZdGQsIBvChY3BpqZNw1DbwT2Opf3OUngDf5xg1J5o1pKu5zNvC84vHr9znqUS2\_\_KbKceSm9rtvo1XfmffjLP3ujIqB7Gj9Ntz44896ttK-asYFKWJNMZ1eYgJlFE7P01Z5LoteznOgMT6GQATyn1-YaUE62GSfJCFbm0okc6Z5\_3KDY2uYSirMegb5EplfQwIPbUQeQcQ3I14xs1IoL-n0hbQuRN5gKlCtQ\_ALZqIg1nMXYgscgYqh-QS0Q-fG\_akSslYwqRN7zjdBlbMHeoEKl1IGLC23HVGASQCnDVjePBSbI9C1iaULdmlwg4DWJVaYFK8JhAOcpUAUpobrdklA2ArkRKYnRYGnMpR-d\_Rqd51xE5ipUS9v\_F3t5zzdABBqAtMYxUZhAtFGQkfgCchQGLM4g5QLUikoQKPlGxKgxU2Krgbzi7JGCFWY5fPjhJxCor2rD-ZOXkPOMxhSlxlpHOBnzHGU\_JtMak1dcwXO9Xv81MLE-ZJWEhKPUyuE1lQqIshggS8yJTQC\_13fstma6v37zYlR3PP9iZGxHrUwnBB79AWMFK2L4RYgMEsxQYdILx3hSw\_GVuUaemNoYnhOaFRKXcPw9oQr2Q\_n4Due504H-8d93O9ATqMYmWREWYHCe-i-JilcjOE\_9V5yh\_To03qAdyshEFGRIpBYOpNFBGkPS196L3EKpDEcaIObI3ovI5KRG5B3n8FKnKkWglYW2DURSs5hqbZ\_oO-nuKCU4NSLlmxKR\_6gR0UtJy2keXSKstIIgtCYZXVOlHYIkZq6dUUvErP8UYQSutHyKrjGAr6V-mXNmI45JVnma6luXun3RnUp9TIRM9UFz4C4\_58XFTXiLQh\_bmKTCG1XQPOuOFcAz\_WsJrQlNtdNLKpUZa9REqADnz\_\_aBqc2FruLg0yBtOOnZJOp3WoOxhI-\_PgnmNiPqf04lh9--LehibDFoltIBRFuOUtg\_8MP\_zQ1c0lRjgBL-RUHzvyYZJkOOWY3iIDc5PqHI6BofIEOgt\_OHziruyLLF2YDe6GLLXo988pE1BuB6zYzr04zvcLlince3M6bLJ-a09OKpQ02TW6lxxWMNKKajeGToTJanLMEr2EBbJNljRH0XZAFJDzerPWMLVE9y1A\_fr49TwY2JRwWzNINszviAlmCYjB0b2xIBbnAy98X1xgWwPAK3qIaVNnTN0Fg7nsEJh94i5m5F\_AkywZe4wqEN\_w2WJN8wGBxBo9ZkBBFJKqADgtWpTxgxA8oYyi-fPfyBSzA8yqanfgg5eIZiVeDAQoxAjrUTOtL\_FZwKl\_rmV64UC0WQOetduZah4NWLJAoLAAbeAm99IZ1H6OTSStfkbXu55mMHx6bnZcSqWBF5IAO4TPwoAQAZuB1OFUwgJGsSXQx-M7NbZtFp72K0akqAE6jjVK8yoL18ccnNwUsWjINjBXr1gMtiU8X3ic39LaRo7dyaedMVx-3fnKDQgTG72\_78vCWtMWxamuA1hD2nNSeNLn8iwqkfJXgbd94LWb1IVTZ03y5d1dzhuSdffjxT\_fuYfypHM1-u89w-gxJb75\_clOGiG80A0WW39aqlwGpJt1HLLsRvnPyzz78y3\_3Tl3bogAcHt\_tnGYb-e-eZHf\_1mwh7pxpTd2lZd5ip3dPyn721a3Zg-hq9Z3V3XWXPesvZ985jmiCkf5dBEuermiWDLRnDp0Ge3vwVpHlEvVeBTK91MUIOjmmQodPQpkCzrJt1YOmMPhNN1gMnQgGOgl6R9fIN2owMOGtDjwvqFQBSZKBV8XWERyH8BgofApHoRNjSvVuW9G1J1hr0\_WGVWSNFGsG1UgxPegzfcXqhUkFUAy8WBf\_3ggGrRBcBWFY6BpR4jlTmqcT9-dOY3c1a4Vr-MysbzBzIzdUq5Wja\_VcPhXbw27T072ygj\_ds9t6p3vmp6j\_C-08FTeaOgAA" htmlZN="2" %}

### Recommended Backoff Parameters

| Error Code |              Initial Delay             | Max Delay | Max Retries | Jitter |
| ---------- | :------------------------------------: | :-------: | :---------: | :----: |
| 429        | From `Retry-After` header (default 5s) |    60s    |      5      |   Yes  |
| 500        |                   1s                   |    30s    |      3      |   Yes  |
| 412        |                   30s                  |    120s   |      2      |   No   |

**Jitter** prevents thundering herd when multiple clients retry simultaneously:

```javascript
const jitter = () => Math.random() * 1000; // Up to 1s of random delay
const backoff = (attempt) => Math.min(1000 * 2 ** attempt, 30_000) + jitter();
```

***

## Error Handling Checklist

Use this checklist before shipping any integration against the Customs Catalog API:

### Request Construction

* [ ] JWT Bearer token is included on every request
* [ ] Token refresh logic is implemented for `401` responses
* [ ] `Content-Type: application/json` is set on all `POST` and `PUT` requests
* [ ] All required path parameters are validated before building the URL
* [ ] `PageNumber` and `PageSize` are always provided to paginated endpoints

### Response Handling

* [ ] HTTP status code is checked before parsing the response body
* [ ] `error.message` is treated as nullable and handled gracefully
* [ ] `202 Accepted` is not treated as completion — async polling is implemented
* [ ] `204 No Content` is handled without attempting to parse a body

### Resilience

* [ ] `429` responses trigger a backoff using the `Retry-After` header
* [ ] `500` responses trigger exponential backoff (max 3 retries)
* [ ] `400` and `404` errors are not retried without fixing the request
* [ ] All unhandled errors are logged with request context for debugging

### Observability

* [ ] Error `code` and `message` fields are captured in logs
* [ ] Request IDs or correlation headers (if available) are logged alongside errors
* [ ] Rate limit events are tracked to identify usage pattern issues
* [ ] `500` error frequency is monitored with alerting thresholds


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/customs-catalog-api/customs-catalog-api/error-handling/retry-strategy-and-checklist.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.