# PlanetGraph API Auth and Error Guide

## Authentication

**Preferred for agents:**
- X-API-Key header

**Alternative:**
- Authorization: Bearer <firebase_id_token>

## Swagger usage
- Open https://api.planetgraph.ai/docs
- Click Authorize
- Fill ApiKeyAuth (X-API-Key)

## Common errors
- **400 Bad Request:** invalid parameters or unsupported query structure
- **401 Unauthorized:** missing or invalid credentials
- **403 Forbidden:** role/ownership violation
- **404 Not Found:** resource does not exist or is deleted
- **409 Conflict:** resource in conflicting state
- **429 Too Many Requests:** rate limit exceeded

## Troubleshooting checklist
1. Verify auth header present.
2. Verify endpoint path and method.
3. Verify filter semantics (edge type vs node type).
4. Reduce filters and test baseline list endpoint.