Error Reference

All API errors return JSON responses with consistent formats. This page documents every error code, its response body, and how to resolve it.

Error Response Format

The API uses three response envelope formats depending on the error type.

Standard errors return a string detail:

{"detail": "Token expired"}

Structured errors (credit-related) return an object with additional context:

{
  "detail": {
    "error": "insufficient_credits",
    "required": 5.0,
    "available": 2.3,
    "deficit": 2.7
  }
}

Rate limit errors include a retry_after value in seconds:

{"detail": "Rate limit exceeded", "retry_after": 60}

The Retry-After HTTP header is also set on 429 responses.

Authentication Errors (401)

Returned when the request has no token, an invalid token, or an expired token.

Token Expired

{"detail": "Token expired"}

Cause: Your JWT access token has passed its expiry time (approximately 1 hour after issue).

Fix: Refresh your token using the refresh token endpoint. See Authentication.

Invalid Token

{"detail": "Invalid token"}

Cause: The JWT signature is invalid, the token is malformed, or it was issued by a different project.

Fix: Verify you are using the correct access_token from the sign-in response. Ensure the token has not been truncated or modified.

Missing Token

{"detail": "Not authenticated"}

Cause: The Authorization header is missing from the request.

Fix: Add the header Authorization: Bearer YOUR_ACCESS_TOKEN to your request. See Using the Token.

Authorization Errors (403)

Returned when the authenticated user lacks permission for the requested action.

Billing Admin Required

{"detail": "Billing admin access required"}

Cause: The endpoint requires the owner or admin role within the organization, but your account has the member role.

Fix: Ask your organization owner to upgrade your role, or use an account with admin privileges.

Validation Errors (400)

Returned when the request body or parameters are invalid.

Invalid Request Body

{
  "detail": [
    {
      "loc": ["body", "question"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Cause: A required field is missing or has an invalid type. The loc array shows the path to the invalid field. The msg describes what went wrong.

Fix: Check the endpoint documentation for required fields and their types. Ensure your Content-Type header is set to application/json.

Invalid Parameter Value

{"detail": "Invalid org_id format"}

Cause: A path or query parameter has an invalid format or value.

Fix: Check the parameter format in the endpoint documentation. Organization IDs and member IDs are UUIDs.

Credit Errors (402)

Returned when the account does not have enough credits for the requested operation.

Insufficient Credits

{
  "detail": {
    "error": "insufficient_credits",
    "required": 5.0,
    "available": 2.3,
    "deficit": 2.7
  }
}

Cause: The operation costs more credits than your organization has available. The response shows exactly how many credits you need (required), have (available), and are short (deficit).

Fix: Purchase additional credits through the billing portal. Use GET /billing/credits/balance to check your current balance before making requests.

Not Found Errors (404)

Returned when the requested resource does not exist.

Resource Not Found

{"detail": "Not found"}

Cause: The resource ID in the URL does not match any existing record. This is also returned for unauthorized admin access (the API does not reveal whether admin endpoints exist to non-admin users).

Fix: Verify the resource ID is correct. Check that you are using the right API base URL.

Alert Type Not Found

{"detail": "Alert type not found: cost_spike"}

Cause: The specified alert type is not recognized by the system.

Fix: Use one of the supported alert type values from the admin API documentation.

Rate Limit Errors (429)

Returned when you have sent too many requests in a given time window.

Rate Limit Exceeded

{"detail": "Rate limit exceeded", "retry_after": 60}

Headers:

Header	Value	Description
`Retry-After`	`60`	Seconds to wait before retrying

Cause: Your organization has exceeded the allowed request rate for this endpoint.

Fix: Wait for the number of seconds specified in retry_after (or the Retry-After header) before retrying. Implement exponential backoff in automated systems. Contact support if you need higher rate limits.

Server Errors (500)

Returned when an unexpected error occurs on the server.

Internal Server Error

{"detail": "Internal server error"}

Cause: An unexpected exception occurred while processing the request.

Fix: Retry the request after a short delay. If the error persists, contact support at support@spatial.properties with the request details (endpoint, parameters, timestamp).

Auth Not Configured

{"detail": "Auth not configured"}

Cause: The server’s JWT validation is not configured. This typically occurs in development environments.

Fix: This is a server-side configuration issue. Contact the platform administrator.

Service Unavailable (503)

Returned when a dependent service is temporarily unavailable.

Billing Service Unavailable

{"detail": "Billing service unavailable"}

Cause: The billing database or payment processor is temporarily unreachable.

Fix: Retry the request after 30 seconds. Billing outages are typically brief. The GET /health endpoint can confirm whether the API itself is running.

Admin Service Unavailable

{"detail": "Service unavailable"}

Cause: The admin observability backend is temporarily unreachable.

Fix: Retry after 30 seconds. If the issue persists, check the API health endpoint.