Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. The body of the response will also have a boolean success field that will be true if the request was successful or false if it was not. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some debugging.

Status codes

Here is a list of the different categories of status codes returned by the Moon Banking API. Use these to understand if a request was successful.

Name: 2xx
Description: A 2xx status code indicates a successful response.

Name: 4xx
Description: A 4xx status code indicates a client error — this means it's an issue on your end.

Name: 5xx
Description: A 5xx status code indicates a server error — which you should rarely see, if ever.

400 - Bad Request

A 400 Bad Request error indicates that the Moon Banking server cannot process your request due to client-side issues. This typically happens when your request has invalid syntax, missing required parameters, or malformed data. The Moon Banking API will return an error response with an error type and message to help you identify and fix the problem.

Error response

{
  "success": false,
  "message": "Input validation failed",
  "code": "BAD_REQUEST",
  "timestamp": "2025-07-12T00:08:07.381Z",
  "version": "2025-07-11",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": [
          "name"
      ],
      "message": "Expected string, received number"
    }
  ]
}

401 - Unauthorized

A 401 Unauthorized error indicates that your request lacks valid authentication credentials. This typically happens when you haven't provided an API key, your API key is invalid or expired, or you're trying to access a resource that requires authentication without proper credentials.

To resolve this error, ensure that you're including a valid API key in your request headers and that your credentials haven't expired.

Error response

{
  "success": false,
  "message": "Test error",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-09-19T22:22:41.362Z",
  "version": "2025-07-11"
}

404 - Not Found

A 404 Not Found error indicates that the server cannot find the requested resource. This typically happens when you're trying to access an endpoint that doesn't exist, using an incorrect URL path, or referencing a resource ID that doesn't exist in the system.

To resolve this error, double-check the URL path, ensure the resource ID is correct, and verify that the endpoint exists in the API documentation.

Error response

{
  "success": false,
  "message": "Test error",
  "code": "NOT_FOUND",
  "timestamp": "2025-09-19T22:23:57.882Z",
  "version": "2025-07-11"
}

408 - Request Timeout

A 408 Request Timeout error indicates that your request took longer than 20 seconds to complete and was automatically terminated by the server. Moon Banking processes all requests within a 20-second timeout window to ensure optimal performance and resource management.

You should rarely, if ever, encounter this error under normal usage. If you do see this error, it may indicate an issue with your request complexity or temporary server-side processing delays. Consider simplifying your request or trying again after a brief wait.

Error response

{
  "success": false,
  "message": "Test error",
  "code": "TIMEOUT",
  "timestamp": "2025-09-19T22:24:38.242Z",
  "version": "2025-07-11"
}

429 - Too Many Requests

A 429 Too Many Requests error indicates that you have exceeded the rate limit for your API key. Moon Banking limits API requests to 100 requests per minute per API key to ensure fair usage and prevent abuse. You may request higher limits by contacting support. Minutes are based on the clock minute, not a rolling minute since your first request.

You may check the following headers to see your rate limit status:

Name: X-Rate-Limit-Per-Minute
Description: The maximum number of requests allowed per minute

Name: X-Rate-Limit-Remaining-Per-Minute
Description: The number of requests remaining in the current minute

Name: X-Rate-Limit-Reset-Per-Minute
Description: The timestamp of the next reset time for the per-minute rate limit

Name: X-Rate-Limit-Retry-After
Description: The number of seconds until the next reset time for the per-minute rate limit. You should wait to retry until this number of seconds has passed. This header will only be present if you have exceeded the rate limit.

Error response

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "timestamp": "2025-10-09T01:31:08.766Z",
  "version": "2025-07-11"
}

500 - Internal Server Error

A 500 Internal Server Error indicates that the Moon Banking API server encountered an unexpected condition that prevented it from fulfilling your request. This is a server-side error that is not caused by your request or client-side issues.

You should rarely, if ever, encounter this error. If you do see this error, it indicates an issue on Moon Banking's end. Please try your request again after a brief wait, and if the problem persists, contact Moon Banking support with the timestamp and details of your request.

Error response

{
  "success": false,
  "message": "Test error",
  "code": "INTERNAL_SERVER_ERROR",
  "timestamp": "2025-09-19T22:25:18.744Z",
  "version": "2025-07-11"
}