Errors
Gateway errors, their codes, and Mustang's own error format.
Errors come from one of two places, and they look different because they are different systems.
Gateway errors
The gateway sits in front of the document service and rejects requests before
they reach it — bad key, no quota, wrong environment. These carry an
X-Error-Code response header with a stable, machine-readable reason.
Check that header rather than string-matching on message, which is prose and
may be reworded.
{
"statusCode": 401,
"message": "API key not valid for this environment",
"errorCode": "ENV_MISMATCH"
}| Status | X-Error-Code | Means | What to do |
|---|---|---|---|
| 401 | MISSING_KEY | No Authorization or apikey header | Send the key |
| 401 | INVALID_KEY | Malformed key, or the signature did not match | Check for truncation or a stray space |
| 401 | UNKNOWN_KEY | Well-formed but not a key we issued | Confirm you copied the whole key |
| 401 | KEY_REVOKED | The key was revoked in the portal | Create a new one; stop retrying |
| 401 | ENV_MISMATCH | The key's environment does not match the service it reached | You are probably mixing a test key with live config |
| 401 | ENV_MISSING | The edge did not state an environment — a misconfiguration on our side | Retry; if it persists, contact support |
| 403 | KEY_EXPIRED | The key is past its expiry | Create a new one |
| 429 | RATE_LIMITED | Too many requests this minute | Back off and retry |
| 429 | QUOTA_EXHAUSTED | Monthly quota spent | Wait for the period to roll over, or raise your plan |
RATE_LIMITED is worth retrying with backoff. QUOTA_EXHAUSTED is not — it
will not clear until the month does.
Both are 429. Retrying a QUOTA_EXHAUSTED in a loop burns your own rate limit
and will never succeed. Branch on X-Error-Code, not on the status.
Mustang errors
Once a request is authorized, the document service handles it and reports its own problems — a malformed XML, a PDF that is not PDF/A, a document that fails validation. These are 4xx from Mustang itself and carry its error shape:
{
"requestUrl": "/api/v1.8.2/e-invoice/validate",
"httpCode": 400,
"errorCode": "…",
"message": "…"
}The practical distinction: a gateway error means the request never happened. A Mustang error means it happened and the document was the problem.
Rate limits
Sandbox and live keys are limited separately, and the sandbox is capped harder because it is a public surface. If you are being limited while developing, that is the sandbox's limit — a live key has its own, higher one.
503
503 means the authentication service could not be reached. The gateway fails
closed rather than letting unauthenticated traffic through, so this is a
temporary outage on our side, not something wrong with your request. Retry with
backoff.