Error Codes
The Tewdy API uses standard HTTP status codes and returns structured JSON error responses.
Error Response Format
All error responses follow this structure:
{
"message": "Human-readable error description",
"code": "MACHINE_READABLE_CODE",
"status": 400
}HTTP Status Codes
| Status | Meaning | Description |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
400 | Bad Request | Invalid request body, missing fields, or validation error |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Authenticated but insufficient permissions |
404 | Not Found | Resource does not exist |
409 | Conflict | Resource already exists or state conflict |
422 | Unprocessable Entity | Validation error with detailed field-level errors |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server error |
502 | Bad Gateway | External service dependency failed |
503 | Service Unavailable | Server temporarily unavailable |
Authentication Error Codes
| Code | Status | Description |
|---|---|---|
TOKEN_MISSING | 401 | No JWT or API key provided |
TOKEN_INVALID | 401 | JWT is malformed or has an invalid signature |
TOKEN_EXPIRED | 401 | JWT has expired |
API_KEY_MISSING | 401 | X-API-Key header is missing |
API_KEY_INVALID | 401 | API key is invalid, expired, or revoked |
SCOPE_INSUFFICIENT | 403 | API key does not have the required scope |
Troubleshooting
”TOKEN_MISSING” or “API_KEY_MISSING”
Make sure you’re sending your API key in the correct header:
# Correct
curl -H "X-API-Key: tewdy_abc123..." https://api.tewdy.com/api/v1/tasks
# Wrong — using Authorization header for API keys
curl -H "Authorization: tewdy_abc123..." https://api.tewdy.com/api/v1/tasks“API_KEY_INVALID”
Your API key may be:
- Revoked — check the key status in your dashboard
- Expired — check the expiration date
- IP restricted — your request IP may not be in the key’s whitelist
- Mistyped — ensure the full key is included (starts with
tewdy_)
“SCOPE_INSUFFICIENT”
Your API key doesn’t have the required scope for this endpoint. For example, creating a task requires tasks:write but your key may only have tasks:read.
To fix: create a new API key with the required scopes, or update the existing key’s scopes in the dashboard.
”429 Too Many Requests”
You’ve exceeded the rate limit. Check the Retry-After header and wait before retrying. See Rate Limiting for details.
”500 Internal Server Error”
This is an unexpected server error. If it persists, contact support with the request details (endpoint, method, timestamp). Do not retry immediately — use exponential backoff.