Error Responses

This document describes the error response format and common error codes used by the Geog API.

Response Format

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": "Error Type",
  "message": "Human-readable error description",
  "code": "MACHINE_READABLE_CODE"
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error`	string	Short error type or title
`message`	string	Detailed, human-readable explanation
`code`	string	Machine-readable error code for programmatic handling

HTTP Status Codes

2xx Success

Code	Status	Description
200	OK	Request successful
204	No Content	Request successful, no response body (e.g., empty tile)

4xx Client Errors

Code	Status	Description
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded

5xx Server Errors

Code	Status	Description
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service failure (e.g., JWKS fetch)
503	Service Unavailable	Service temporarily unavailable

Error Codes Reference

Authentication Errors

AUTH_REQUIRED

Status: 401 Unauthorized

Cause: Request lacks authentication credentials.

Response:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header",
  "code": "AUTH_REQUIRED"
}

Resolution: Include a valid Bearer token in the Authorization header.

INVALID_TOKEN

Status: 401 Unauthorized

Cause: JWT token is malformed or invalid.

Response:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid token format",
  "code": "INVALID_TOKEN"
}

Resolution: Ensure the token is a valid self-issued JWT.

TOKEN_EXPIRED

Status: 401 Unauthorized

Cause: JWT token has expired.

Response:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Token has expired",
  "code": "TOKEN_EXPIRED"
}

Resolution: Refresh the token or re-authenticate.

INSUFFICIENT_SCOPE

Status: 403 Forbidden

Cause: Token lacks required permission scope.

Response:

{
  "success": false,
  "error": "Forbidden",
  "message": "Token does not have required scope: tiles:read",
  "code": "INSUFFICIENT_SCOPE"
}

Resolution: Request a token with the required scopes.

JWKS_FETCH_FAILED

Status: 502 Bad Gateway

Cause: Unable to fetch JWKS for token validation.

Response:

{
  "success": false,
  "error": "Bad Gateway",
  "message": "Failed to fetch JWKS",
  "code": "JWKS_FETCH_FAILED"
}

Resolution: Retry the request. Contact support if persistent.

Vector Tiles Errors

INVALID_EXTENSION

Status: 400 Bad Request

Cause: Tile request uses unsupported file extension.

Response:

{
  "success": false,
  "error": "Bad Request",
  "message": "Invalid tile extension. Must be 'mvt' or 'pbf'",
  "code": "INVALID_EXTENSION"
}

Resolution: Use .mvt or .pbf extension in tile requests.

TILE_NOT_FOUND

Status: 404 Not Found

Cause: Requested tile does not exist or is outside valid zoom range.

Response:

{
  "success": false,
  "error": "Not Found",
  "message": "Tile not found at z/x/y",
  "code": "TILE_NOT_FOUND"
}

Resolution: Verify tile coordinates are within valid range for the tileset.

TILESET_NOT_FOUND

Status: 404 Not Found

Cause: Requested tileset does not exist.

Response:

{
  "success": false,
  "error": "Not Found",
  "message": "Tileset 'unknown' not found",
  "code": "TILESET_NOT_FOUND"
}

Resolution: Verify tileset name is correct.

Rate Limiting Errors

RATE_LIMIT_EXCEEDED

Status: 429 Too Many Requests

Cause: Client has exceeded rate limit.

Response:

{
  "success": false,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Headers:

Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699999999

Resolution: Wait for the rate limit window to reset. Implement exponential backoff.

Validation Errors

VALIDATION_ERROR

Status: 400 Bad Request

Cause: Request body failed validation.

Response:

{
  "success": false,
  "error": "Bad Request",
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "email",
      "message": "Must be a valid email address"
    }
  ]
}

Resolution: Check the details array for specific field errors.