Errors

How the API returns errors and how to handle them.

The API uses conventional HTTP status codes and returns a JSON body with every error. Handle errors in this order:

1. Branch on the HTTP status code. It tells you whether the request was malformed, unauthenticated, not permitted, not found, in conflict, rate limited, or failed on our side.
2. Then branch on code. Every error except a validation failure carries a stable, machine-readable code.
3. Never branch on message. It is written for humans and its wording can change.

Both environments return the same shapes.

Error response format

Every error except a validation failure has the same two-field body:

{
  "message": "Card with id 6b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e not found",
  "code": "CARD_NOT_FOUND"
}

• message — a human-readable description of what went wrong.
• code — an UPPER_SNAKE_CASE identifier you can branch on. The full list is in Error codes below.

Validation errors (400)

When the request fails schema validation — a required field is missing, a value has the wrong type or format, a path or query parameter is malformed — the body is a list of offending fields instead of { message, code }:

{
  "errors": [
    {
      "msg": "Invalid value",
      "param": "external_id",
      "location": "body"
    }
  ]
}

• msg — a human-readable description of the problem with this field.
• param — the name of the field, without any parent path.
• location — where the field was read from: body, query or params.

Two rules to encode in your client:

• Query parameters are validated the same way: GET /v2/api-gateway/cards?limit=50 returns {"errors":[{"msg":"Too big: expected number to be <50","param":"limit","location":"query"}]}.
• Validation bodies never include the rejected value, and never include top-level message or code. Detect a validation error by the presence of errors.

Some 400 responses are not validation failures but business rules — not enough balance, a card product that does not support the operation, a required id missing on a create. Those use the standard { message, code } body. Endpoint pages list which code values each operation can return.

Authentication errors (401)

Returned when the x-api-key header is missing, unknown, inactive, or not enabled for the API. The body follows the standard shape:

HTTP/1.1 401 Unauthorized

{"message":"Invalid API Key","code":"UNAUTHORIZED"}

message is Authentication required (no credentials sent), Invalid API Key (unknown or inactive key), or User is not allowed to access the API Gateway (the key's account is not enabled for the API). An invalid or expired cardholder token also returns 401 UNAUTHORIZED. See Authentication.

A 403 with code: "FORBIDDEN" means the credentials are valid but this action is not allowed for them — for example a cardholder token used on an endpoint that requires an organization API key, or an account whose API access has been restricted.

Requests that never reach an endpoint

Three kinds of request are rejected before they reach an endpoint and return a different, six-field body: an unknown path (typo in the URL, wrong version prefix), a request body that is not valid JSON, and a body larger than the size limit.

GET https://api.themooncard.com/v2/api-gateway/nope

HTTP/1.1 404 Not Found

{
  "statusCode": 404,
  "code": "HTTP_EXCEPTION",
  "message": "Cannot GET /v2/api-gateway/nope",
  "timestamp": "2026-08-16T19:39:42.900Z",
  "path": "/v2/api-gateway/nope",
  "requestId": "04127f3f-630b-440e-a085-79a82f8d63b9"
}

A malformed JSON body returns 400 with the same six fields ("message": "Unterminated string in JSON at position 10 …"). Write your error parser to accept this shape: read the HTTP status, then treat a body with errors as a validation failure, and otherwise read code and message. The presence of statusCode in the body tells you the request never reached an endpoint.

HTTP status codes

422 and 501 are not used.

Error codes

Codes are grouped by the HTTP status they are returned with. A code always comes with the same status unless noted. Endpoint pages list the codes each operation can return.

400 — request rejected by a business rule

401 — not authenticated

403 — not permitted

404 — not found

The message is usually <Resource> with id <id> not found or <Resource> not found. Resources that belong to another organization are reported as not found.

409 — conflict

429 — too many requests

500 — server error

503 — temporarily unavailable

Card declines are not HTTP errors

A declined card transaction is not returned as a 4xx on an API call. Declines are delivered asynchronously as a CARD_DECLINE webhook with a customer_friendly_description and a decline_type_id you can branch on. Do not treat an HTTP error as a decline, or a decline as an HTTP error.

Retries and idempotency

Send an idempotency key and any POST becomes safe to retry. With Idempotency-Key set, a repeat of a request that timed out returns the first attempt's result instead of performing the operation again — that is the mechanism this section used to work around.

Without a key, a request that timed out may or may not have landed, so retry according to what the operation does:

How to check before retrying a create, when it was sent without a key:

• Card issued? List cards for the cardholder — GET /v1/api-gateway/card?external_id=… or GET /v2/api-gateway/cards?external_id=… — and look for a card created after your request. Both lists are newest first. V1 card create also debits your prepaid balance, so a second attempt that lands charges you twice.
• Balance added or moved? Fetch the card (balance) or its transactions with include_loads=true; for accounts, GET /v2/api-gateway/accounts/{id} or its transactions.
• Account, organization or velocity control created? List them and match on the name or target you sent.

General rules:

• Retry 429 after Retry-After, and 5xx with exponential backoff and jitter. Cap retries; if a 503 MAINTENANCE_MODE persists, wait minutes, not seconds.
• Do not retry other 4xx unchanged — the request needs to change first. A changed request needs a new idempotency key.
• Webhook deliveries can be retried by Moon; deduplicate on webhook_event_id and always return HTTP 200 from your webhook endpoint.

Getting help with an error

Every response to a request that reached an endpoint carries an x-correlation-id header (send your own value and it is echoed back). Log it together with the status and the full body. When you contact our team, quote the correlation id, the endpoint, the timestamp and the response body — that lets us find the request. Responses rejected before an endpoint (401, 403 from authentication, 429, unknown paths) do not carry the header; for the six-field body quote its requestId instead.

Show message to your own users only after mapping it to your own copy — the wording can change; code will not.

Last updated August 17, 2026