# Errors and status codes

Read Moolre response envelopes, distinguish transport errors from API errors, and surface actionable failures to users.

## Read the response envelope first

Moolre responses include a status value, a code, a message, data, and an optional go value. Use the HTTP status for transport-level handling, then use the response code and message to decide what the application should do next.

Treat successful HTTP responses with an application error payload as an API-level failure. Keep the code and a correlation value in your logs so support can trace the request quickly.

## Handle failures deliberately

Show people a clear next step instead of exposing raw API messages. Validation failures normally need corrected input, while timeouts and 5xx responses may be retried safely when an idempotency reference is present.

- 400-range errors: correct the request, credentials, or referenced resource before retrying.
- 401 and 403 errors: verify the environment, API user, and the credential expected by that endpoint.
- 429 and 5xx errors: wait, back off, and retry only with the same external reference.