How to Use Error Codes and traceId

The error code is the machine contract. HTTP status describes the broad outcome, safe args add approved context, message helps a person, and traceId connects evidence for one request. These fields have different jobs.

Branch only on code

Use the documented stable code as the only machine decision key. Do not compare English, Chinese, Vietnamese, or Indonesian message text.

For How to Use Error Codes and traceId, treat “Branch only on code” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Use HTTP status as a category

Treat 4xx as a request, authentication, permission, state, or limit problem and 5xx as a service failure category, while still reading the code.

For How to Use Error Codes and traceId, treat “Use HTTP status as a category” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Display message safely

Message is intended for a person and may be localized or safely fall back to English. It must not be parsed to discover state or internal details.

For How to Use Error Codes and traceId, treat “Display message safely” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Use args only as documented

Args contain safe structured values for interpolation or context. Validate their names and types; do not assume they include every internal value.

For How to Use Error Codes and traceId, treat “Use args only as documented” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Preserve traceId exactly

Store the traceId returned with the failed request and include it in support evidence. Do not invent a traceId from an order number or email.

For How to Use Error Codes and traceId, treat “Preserve traceId exactly” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Decide retries by semantics

Authentication, validation, maxPrice, ownership, and idempotency conflicts need correction or query, not blind retries. A transient failure may permit a bounded retry.

For How to Use Error Codes and traceId, treat “Decide retries by semantics” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Protect logs

Log code, HTTP status, endpoint class, safe request identity, timing, and traceId. Mask API keys, signatures, tokens, phone numbers, and sensitive payloads.

For How to Use Error Codes and traceId, treat “Protect logs” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Report one failed request

Provide the timestamp, endpoint, code, HTTP status, traceId, safe parameters, and expected result. Keep the raw secret and unrelated data out of the report.

For How to Use Error Codes and traceId, treat “Report one failed request” as one checkpoint rather than a reason to change several settings at once. Record what you saw, make one justified change, and keep the related order or account reference.

Practical checklist

1. Verify branch only on code, record the result, and continue only when the next action is clear.
2. Verify use http status as a category, record the result, and continue only when the next action is clear.
3. Verify display message safely, record the result, and continue only when the next action is clear.
4. Verify use args only as documented, record the result, and continue only when the next action is clear.
5. Verify preserve traceid exactly, record the result, and continue only when the next action is clear.
6. Verify decide retries by semantics, record the result, and continue only when the next action is clear.
7. Verify protect logs, record the result, and continue only when the next action is clear.
8. Verify report one failed request, record the result, and continue only when the next action is clear.

Use the final platform status and account history as the source of truth. Do not share passwords, full verification codes, authentication secrets, access tokens, or API keys in screenshots or support messages. More guidance is available in the MangoOTP Help Center.