# Errors & Error Handling
SUMMARY: HTTP status codes, error response format, and how to recover from common errors.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

Errors & Error Handling
Synapse uses standard HTTP status codes with a consistent error response format.
This page explains how to interpret and recover from errors.
Error Response Format
All errors return JSON with this structure:
[CODE BLOCK]
| Field | Description |
|-------|-------------|
|  | HTTP status code |
|  | HTTP status name |
|  | Human-readable error description |
|  | URL to relevant documentation (when applicable) |
HTTP Status Codes
200 OK
Success. The request was processed correctly.
201 Created
Success. A new resource was created (e.g. ).
204 No Content
Success. No body returned (e.g. ).
400 Bad Request
The request was malformed. Common causes:
- Missing required JSON fields
- Invalid JSON syntax
- Invalid enum value (e.g. wrong category)
[CODE BLOCK]
Fix: Check the request body against the API docs. Ensure all required
fields are present and have valid values.
401 Unauthorized
Authentication failed. Common causes:
- Missing  header
- Invalid Mind Key or JWT
- Using a Mind Key where a JWT is required (or vice versa)
[CODE BLOCK]
Fix: Verify your token. See Authentication.
403 Forbidden
You're authenticated but not allowed to perform this action. Common causes:
- Trying to delete another user's mind
- Trying to verify a memory with a Mind Key (requires JWT)
- Mind is disabled
Fix: Check if you're using the correct token type for this endpoint.
404 Not Found
The requested path or resource doesn't exist.
> [!CRITICAL]
> Do NOT guess endpoint paths. Only the paths listed in 
> exist. If you get a 404, you used a wrong path.
[CODE BLOCK]
Fix: Call  to see the list of valid endpoints. Compare
your URL against the list character-by-character.
409 Conflict
The request conflicts with existing state. Common causes:
- Trying to register with an email that already exists
- Duplicate webhook URL
Fix: Use a different value, or use  to update the existing resource.
429 Too Many Requests
You hit a rate limit. Only applies to  query parameter auth (60/min).
[CODE BLOCK]
Response headers:
[CODE BLOCK]
Fix: Switch to  header (no rate limit), or wait
 seconds.
500 Internal Server Error
Server error. This shouldn't happen — if it does, it's a bug.
Fix:
1. Retry with exponential backoff (1s, 2s, 4s, 8s)
2. Check  to see if the server is up
3. If persistent, report the error
503 Service Unavailable
Server is temporarily down (e.g. during deployment, database migration).
Fix: Wait and retry. Check .
Recovery Patterns
Retry with exponential backoff
[CODE BLOCK]
Auth error handling
[CODE BLOCK]
Common Error Scenarios
"Mind Key fehlt oder ungültig"
- You forgot the  header
- You used  but the key is wrong
- You're using a JWT where a Mind Key is required
"Route not found"
- You guessed a path that doesn't exist
- You used a verb wrong (e.g.  vs )
- Check  for valid paths
"Rate limit exceeded"
- You're using  and exceeded 60 req/min
- Switch to  header
Next Steps
- Authentication
- API Overview
- Rate Limits