Errors

Errors tell you whether to fix the request, fix credentials, wait, or escalate. The Order API uses ordinary HTTP status codes and a small JSON body with a status, a human-readable message (sometimes a list of validation messages), and an error label.

Categories of failure

Validation failures mean the payload or query does not match what Chargee accepts — wrong types, missing required fields, forbidden unknown fields, or values outside allowed ranges. These are not intermittent; changing nothing and retrying will fail the same way.

Authentication failures mean Chargee could not establish a trusted actor: bad login, missing or expired token, or an inactive account. Fix identity before retrying business calls.

Not found for orders usually means “not found for you.” Cross-account privacy and missing ids look the same from the client’s point of view.

Conflicts protect uniqueness: registering with an email or Monta username that already exists, or creating an order whose webshop id is already owned in Chargee (by you or someone else). Conflicts are intentional guards, not transient glitches.

Too many requests means the shared Monta budget cannot accept more warehouse work right now. Waiting and backing off is the correct response.

Server and upstream failures cover unexpected Chargee problems and cases where Monta does not answer usefully (including timeouts). Limited retries with backoff can help; persistent 5xx needs investigation.

Validation philosophy

Chargee validates at the edge: unknown fields are rejected, only declared fields are kept, and types are coerced where that is safe. That strictness prevents silent data loss and “extra” properties that never meant anything to the server.

Conflicts and safe retries

Re-creating the same webshop order id is a conflict, not an upsert. Import, by contrast, is built to be re-runnable: orders you already fully hold with serials are skipped instead of failing the whole job. Knowing which operations are “create once” versus “run again safely” saves a lot of error handling complexity.

A simple retry policy

Do not retry validation, auth, not-found, or conflict errors without changing the input or credentials. Do retry rate limits after a delay. Treat server errors as maybe-transient, with a small retry budget and alerting if they continue. Map Monta-originated failures the same way you would map any upstream dependency: the status often reflects what Monta returned, but the responsibility to your user is still yours.