Skip to main content
The Moonbase API returns structured error responses with standard HTTP status codes.

​
Error response format

All error responses follow a consistent JSON structure: 
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The 'email' field is required but was not provided."
    }
  ]
}
Each error object contains:
  • status: The HTTP status code as a string
  • title: A brief, human-readable summary of the error
  • detail: A more detailed explanation of what went wrong (when available)

​
Status Codes

Responses include standard HTTP status codes to indicate success or failure:
Status CodeTitleDescription
400Bad RequestThe request is malformed or contains invalid parameters.
401UnauthorizedAuthentication failed or was not provided.
403ForbiddenRequest understood; API key lacks resource access.
404Not FoundThe requested resource doesn’t exist.
409ConflictRequest conflicts with current state.
422Unprocessable EntityThe request was well-formed but contains semantic errors.
429Too Many RequestsToo many requests in a given amount of time (rate-limiting).
500Internal Server ErrorServer-side issues for Moonbase
503Service UnavailableThe server is temporarily unavailable.

​
Response headers

All responses from the API include an x-request-id header. This is a unique identifier for the request. When contacting support, include this ID.

​
Common error scenarios

​
Authentication errors (401)

Cause: Missing, invalid, or expired API key Solution:
  • Verify API key is present in Authorization header
  • Check the API key is valid in organization settings
  • Regenerate if the key may have been compromised

​
Rate limiting errors (429)

Cause: Too many requests sent in a short time period Solution:
  • Implement exponential backoff retry logic
  • Space out requests to stay within rate limits
  • See the rate limiting guide for detailed information

​
Validation errors (422)

Cause: Request data fails validation rules Solution:
  • Check the detail field in the error response for specific validation messages
  • Verify required fields are included
  • Ensure field values meet format and length requirements

​
Server errors (500, 503)

Cause: Temporary server-side issues for Moonbase Solution:
  • Retry the request after a brief delay
  • If the problem persists, contact support with the x-request-id from the API response
  • Implement error handling

​
Best practices

  • Log error details: Capture both the status code and error message for debugging
  • Include request IDs: Log the x-request-id header for support requests
  • Validate locally first: Check required fields and formats before making API calls
  • Implement error handling: Handle all response scenarios