Error Codes

Quick Reference

HTTP Status	Error Code	When It Occurs
400	MISSING_PARAMETER	A required query parameter is not provided
400	INVALID_PARAMETER	A parameter value is out of range or the wrong type
401	INVALID_API_KEY	The API key is missing, invalid, or revoked
403	PLAN_UPGRADE_REQUIRED	The feature is not included in your plan (never consumes credits)
404	NOT_FOUND	The resource does not exist or does not belong to your account
409	JOB_NOT_READY	A batch job's results were requested before completion
429	RATE_LIMIT_EXCEEDED	Too many requests per second for your plan tier
429	QUOTA_EXCEEDED	Credit quota exhausted for the current window (daily on Free, monthly on paid plans)
500	INTERNAL_ERROR	Unexpected server-side failure (credits automatically refunded)
502	INTERNAL_ERROR	An upstream engine (geocoding/routing) failed
503	SERVICE_UNAVAILABLE	The feature is not provisioned on this deployment yet (retryable)

Error Format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "field": "parameter_name",
    "retry_after": 1,
    "quota_reset": 1753056000,
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Field	Type	Present	Description
code	string	Always	Machine-readable error code
message	string	Always	Human-readable error description
field	string	MISSING_PARAMETER, INVALID_PARAMETER only	The parameter that caused the error
retry_after	integer	RATE_LIMIT_EXCEEDED only	Seconds to wait before retrying
quota_reset	integer	QUOTA_EXCEEDED only	Unix timestamp when the quota window resets
upgrade_url	string	PLAN_UPGRADE_REQUIRED, QUOTA_EXCEEDED	Where to upgrade the plan

Error Details

MISSING_PARAMETER

HTTP Status: 400

Returned when a required query parameter is not provided in the request.

Fix: Add the missing parameter to your request. Check the endpoint documentation for required parameters.

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'q' is missing",
    "field": "q"
  }
}

INVALID_PARAMETER

HTTP Status: 400

Returned when a parameter value is out of the allowed range or has an incorrect type.

Fix: Check the parameter constraints in the endpoint documentation and correct the value.

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'lat' must be between -90 and 90",
    "field": "lat"
  }
}

INVALID_API_KEY

HTTP Status: 401

Returned when the X-Api-Key header or api_key query parameter is missing, malformed, or refers to a revoked key.

Fix: Verify your API key in the Dashboard. Regenerate the key if it has been revoked.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key missing or invalid"
  }
}

PLAN_UPGRADE_REQUIRED

HTTP Status: 403

Returned when your plan does not include the requested feature: a vehicle profile (bike/foot need Startup+, truck/moto need Growth+), an isochrone/matrix size beyond your plan's cap, elevation, vector tiles, or batch geocoding. A 403 never consumes credits.

Fix: Upgrade via the upgrade_url, or adjust the request to your plan's capabilities (see Credits & quotas).

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Profile 'truck' requires the growth plan or higher",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

RATE_LIMIT_EXCEEDED

HTTP Status: 429

Returned when you exceed the per-second rate limit for your plan tier. The retry_after field indicates how many seconds to wait.

Fix: Implement exponential backoff. See Rate Limiting for a code example.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 1 second",
    "retry_after": 1
  }
}

QUOTA_EXCEEDED

HTTP Status: 429

Returned when your credit quota is exhausted for the current window: the day (midnight UTC reset) on Free, the calendar month on paid plans. The quota_reset field is the Unix timestamp when the window resets.

Fix: Upgrade your plan for a bigger envelope, or wait for the reset.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Quota exceeded. Upgrade your plan to continue.",
    "quota_reset": 1753056000,
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

INTERNAL_ERROR

HTTP Status: 500

Returned when an unexpected error occurs on the server side.

Fix: Retry the request once after a short delay. If the error persists, contact support. Any credits debited for a request that ends in a 5xx are automatically refunded.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later"
  }
}

JOB_NOT_READY

HTTP Status: 409

Returned by GET /v1/batch/{job_id}/result while the job is still queued or running (or after it failed).

Fix: Poll GET /v1/batch/{job_id} until status is completed, then download the results.

{
  "error": {
    "code": "JOB_NOT_READY",
    "message": "Job is 'running': results are only available once completed"
  }
}

SERVICE_UNAVAILABLE

HTTP Status: 503

Returned when a feature exists but is not provisioned on this deployment yet (e.g. autocomplete while its instances are being rolled out).

Fix: Retry later; this is a temporary, deployment-side condition.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Autocomplete is not provisioned on this deployment yet"
  }
}