Error Handling

The API uses standard HTTP status codes and returns detailed error information.

Error Response Format

All errors follow the RFC 7807 Problem Details format:

{
  "type": "/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "instance": "/api/v2/photos?date_min=invalid",
  "errors": [
    {
      "field": "date_min",
      "value": "invalid",
      "message": "Must be in YYYY-MM-DD format",
      "example": "2024-01-15"
    }
  ]
}

HTTP Status Codes

Code	Name	Meaning
200	OK	Request successful
304	Not Modified	Cached response is still valid
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	API temporarily offline

Common Errors

401 - Missing API Key

{
  "type": "/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key required. Include your key in the X-API-Key header."
}

Solution: Add the X-API-Key header to your request.

401 - Invalid API Key

{
  "type": "/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key. Check your key or generate a new one at marsvista.dev"
}

Solution: Verify your API key is correct. If lost, regenerate at your dashboard.

400 - Validation Error

{
  "type": "/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "errors": [
    {
      "field": "rovers",
      "value": "invalid_rover",
      "message": "Unknown rover. Valid options: curiosity, perseverance, opportunity, spirit"
    }
  ]
}

Solution: Check the errors array for specific field issues and examples.

429 - Rate Limited

{
  "type": "/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the hourly rate limit of 10000 requests.",
  "retryAfter": 1523
}

Solution: Wait retryAfter seconds, then retry. See the rate limits guide for optimization tips.

404 - Resource Not Found

{
  "type": "/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Rover 'viking' not found"
}

Solution: Check the resource identifier. Use the list endpoints to find valid IDs.

Error Handling Example

async function fetchMarsPhotos(params) {
  const response = await fetch(
    `https://api.marsvista.dev/api/v2/photos?${new URLSearchParams(params)}`,
    { headers: { 'X-API-Key': API_KEY } }
  );

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        throw new Error('Invalid API key. Please check your credentials.');

      case 429:
        // Wait and retry
        const waitTime = error.retryAfter || 60;
        console.log(`Rate limited. Retrying in ${waitTime}s...`);
        await new Promise(r => setTimeout(r, waitTime * 1000));
        return fetchMarsPhotos(params);

      case 400:
        // Show validation errors to user
        const messages = error.errors?.map(e =>
          `${e.field}: ${e.message}`
        ).join('\n');
        throw new Error(`Invalid request:\n${messages}`);

      default:
        throw new Error(error.detail || 'An error occurred');
    }
  }

  return response.json();
}