Skip to main content

​
HTTP status codes

​
Common error responses

​
400 Bad Request

The request is malformed or missing required fields.
Causes:
  • Missing required JSON fields
  • Invalid parameter types (e.g., string instead of number)
  • Out-of-range values (e.g., limit > 100)
Fix: Review the endpoint documentation and validate your request payload. 
{
  "error": "Bad Request",
  "message": "Field 'limit' must be between 1 and 100"
}

​
401 Unauthorized

The Authorization header is missing, malformed, or the API key is invalid.
Causes:
  • Missing Authorization header
  • Incorrect header name (e.g., authorization instead of Authorization)
  • Invalid or expired API key
  • Key was revoked
Fix:
  1. Verify the header is spelled Authorization (capital A).
  2. Ensure the key starts with orbit_.
  3. Rotate the key if it was leaked.
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

​
403 Forbidden

The API key is valid, but the user lacks permission for this action.
Causes:
  • User role doesn’t have the required permission
  • Workspace is restricted
Fix: Contact the workspace admin to grant the necessary permissions. 
{
  "error": "Forbidden",
  "message": "User does not have permission to access this resource"
}

​
404 Not Found

The requested resource doesn’t exist.
Causes:
  • Invalid workspace ID
  • Invalid endpoint path
  • Resource was deleted
Fix: Verify the workspace ID and endpoint path are correct. 
{
  "error": "Not Found",
  "message": "Workspace with ID 12345 not found"
}

​
429 Too Many Requests

You’ve exceeded the rate limit (100 requests/minute per API key).
Causes:
  • Too many requests in a short time
  • Concurrent requests from multiple clients using the same key
Fix:
  1. Implement exponential backoff: wait 1s, 2s, 4s before retrying.
  2. Cache GET responses to reduce requests.
  3. Consider using a separate API key for read-heavy operations.
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds."
}

​
500 Internal Server Error

The Orbit API encountered an unexpected error.
Causes:
  • Server bug
  • Database connectivity issue
  • Temporary outage
Fix:
  1. Retry the request after a short delay (exponential backoff).
  2. Check the status page for known issues.
  3. If the issue persists, contact support with the X-Request-ID header value.
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later."
}

​
Response headers

All API responses include helpful headers:
  • X-Request-ID: Unique request identifier for debugging. Include this when reporting issues.
  • X-RateLimit-Limit: Maximum requests per minute (100).
  • X-RateLimit-Remaining: Requests remaining in the current window.
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets.

​
Debugging tips

Always log the X-Request-ID when an error occurs—it helps support team triage issues faster.
  1. Check the status page: status.planetaryapp.us
  2. Verify your API key: Go to Workspace → Settings → Public API and confirm the key is active.
  3. Test with cURL: Use the API reference examples to isolate the issue.
  4. Review the request: Ensure all required fields are present and correctly formatted.
  5. Check rate limits: Look at the X-RateLimit-Remaining header to see if you’re hitting the limit.

​
Still stuck?