Errors and failures

Handling a failure

1. Branch on `errorCode`. Not on message — it carries substituted values and is written for a person. messageFormat is the stable string if you need to group errors in a log.
2. Show `message`, log `transactionId`. The id is what support traces the call by, and a failure report without one costs a day.
3. Use `propertyName` to point at the field. Where the failure is about one request field, it names it — that is the difference between a form that highlights the problem and a toast that does not.
4. Retry a 500 once, not a 400. A 400 is a decision and will be the same decision next time. A 401 means fetch a new token and retry once.

The published codes

The catalogue is at Error codes: 290 codes with the APIs that raise each one, downloadable as CSV and JSON from the same page. It is the whole of what is published — the specifications declare the 400 envelope but not a single code value, so a code you meet that is not in that list is one to report rather than one to guess at.

The platform emits 1310 distinct error codes across the six published APIs. 290 of them say something beyond their own name, and those are the ones listed here. The other 1020 arrive carrying only the identifier repeated back — no text, or text that restates the name — so this page leaves them out rather than padding itself with rows that answer nothing. A code you meet in a response and cannot find here is one of those. Descriptions the platform emits in Turkish were translated; where the export had already corrupted the text the translation was made by reading through the damage, and those nine are named in content/errors-translations.yaml.

Failures that are not 400s