Error Codes

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.