API Reference

Error Codes

HTTP status codes and error responses returned by the maps.guru API.

The maps.guru API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Success Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Request succeeded, no body returned

Client Error Codes

Code	Meaning	Description
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Valid auth but insufficient permissions
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists
`422`	Unprocessable Entity	Validation error
`429`	Too Many Requests	Rate limit or quota exceeded

Server Error Codes

Code	Meaning	Description
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Upstream service unavailable
`503`	Service Unavailable	Service temporarily down

Error Response Format

All errors return a consistent JSON structure:

{
  "statusCode": 400,
  "message": "Invalid query parameter: q is required",
  "data": {
    "field": "q",
    "code": "required"
  }
}

Common Errors

Missing API Key (403)

{
  "statusCode": 403,
  "message": "Missing API key - Get your FREE key at https://maps.guru/dashboard/tokens"
}

Fix: Add your API key via the key query parameter, Authorization: Bearer header, or X-API-Key header.

Invalid API Key (403)

{
  "statusCode": 403,
  "message": "Invalid API key - Check your key at https://maps.guru/dashboard/tokens"
}

Fix: Verify your API key is correct and hasn't been revoked.

Quota Exceeded (429)

{
  "statusCode": 429,
  "message": "Monthly quota exceeded for maps service. Upgrade your plan at https://maps.guru/dashboard/billing"
}

Fix: Wait for the monthly reset or upgrade your plan.

Validation Error (422)

{
  "statusCode": 422,
  "message": "Validation failed",
  "data": {
    "lat": "Latitude must be between -90 and 90",
    "lng": "Longitude must be between -180 and 180"
  }
}

Fix: Check the data field for specific field-level errors.

REST API

Complete reference for all maps.guru REST API endpoints.

Pagination

How to paginate through large result sets in the maps.guru API.