Errors

All error responses return a JSON object with a message field.

Error format

{
  "message": "Description of what went wrong"
}

Some errors include additional fields for context:

{
  "message": "Validation failed",
  "errors": ["lat is required", "dataset is required"]
}

Common error codes

Status	Code	Description
400	Bad Request	Missing or invalid parameters. Check the message for details.
401	Unauthorized	Missing x-api-key header.
403	Forbidden	Invalid, expired, or suspended API key.
404	Not Found	Dataset not found, or no matching feature.
429	Too Many Requests	Rate limit or monthly quota exceeded. See Limits & Pricing.

400 — Bad Request

Returned when required parameters are missing or values are invalid.

# Missing required parameter
curl -s "https://api.terranode.co/v1/pip?lat=40.7128" \
  -H "x-api-key: YOUR_API_KEY"

{
  "message": "lng is required"
}

# Invalid coordinate
curl -s "https://api.terranode.co/v1/pip?lat=999&lng=-74.006&dataset=us-states" \
  -H "x-api-key: YOUR_API_KEY"

{
  "message": "lat must be between -90 and 90"
}

429 — Too Many Requests

Returned when you exceed your rate limit or monthly quota. The response includes headers to help you manage your usage:

Header	Description
Retry-After	Seconds to wait before retrying

Rate limit exceeded: Wait and retry. The rate limit resets per second.

Monthly quota exceeded: Your quota resets on the 1st of each month at midnight UTC. Upgrade your tier for a higher limit.