Errors

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 Code	Title	Description
`400`	Bad Request	The request is malformed or contains invalid parameters.
`401`	Unauthorized	Authentication failed or was not provided.
`403`	Forbidden	Request understood; API key lacks resource access.
`404`	Not Found	The requested resource doesn’t exist.
`409`	Conflict	Request conflicts with current state.
`422`	Unprocessable Entity	The request was well-formed but contains semantic errors.
`429`	Too Many Requests	Too many requests in a given amount of time (rate-limiting).
`500`	Internal Server Error	Server-side issues for Moonbase
`503`	Service Unavailable	The 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

⌘I

Introduction

Core Concepts

API Reference

Error response format

Status Codes

Response headers

Common error scenarios

Authentication errors (401)

Rate limiting errors (429)

Validation errors (422)

Server errors (500, 503)

Best practices

​Error response format

​Status Codes

​Response headers

​Common error scenarios

​Authentication errors (401)

​Rate limiting errors (429)

​Validation errors (422)

​Server errors (500, 503)

​Best practices

Error response format

Status Codes

Response headers

Common error scenarios

Authentication errors (401)

Rate limiting errors (429)

Validation errors (422)

Server errors (500, 503)

Best practices