Errors
Handle API errors and response codes
Error Handling
SurveyNinja API uses standard HTTP status codes to indicate the success or failure of requests. All errors are returned in a unified JSON format.
Download the markdown version of the "Error Handling" section for use in ChatGPT / other LLMs:
AI Markdown
/static/api/errors.md
AI Markdown
Error Format
Error response structure
All errors are returned in a unified format with an error code, message and additional details.
Error example
{
"success": false,
"error": {
"code": "validation_error",
"message": "The 'title' field is required",
"details": {
"field": "title",
"value": null,
"constraint": "required"
},
"request_id": "req_1234567890",
"timestamp": "2024-01-15T10:30:00Z"
}
} HTTP Status Codes
Success responses
| Code | Description | Usage |
|---|---|---|
| 200 | OK | Successful GET, PUT request |
| 201 | Created | Successful POST request |
| 204 | No Content | Successful DELETE request |
Client errors (4xx)
| Code | Description | Reason |
|---|---|---|
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Missing or invalid token |
| 403 | Forbidden | Insufficient access rights |
| 404 | Not Found | Resource not found |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
Server errors (5xx)
| Code | Description | Action |
|---|---|---|
| 500 | Internal Server Error | Retry the request later |
| 502 | Bad Gateway | Temporary service unavailability |
| 503 | Service Unavailable | Service is temporarily unavailable |
API Error Codes
Authentication errors
unauthorized
Invalid authorization token
{
"status": false,
"error": {
"code": "unauthorized",
"message": "Invalid authorization token"
}
} token_expired
Token has expired and needs to be refreshed
access_denied
Access to the resource is denied
access_denied_to_folder
Access to the folder is denied
Validation errors
validation_error
Data validation error
{
"success": false,
"error": {
"code": "validation_error",
"message": "Validation errors",
"details": {
"errors": [
{
"field": "title",
"message": "The field is required"
},
{
"field": "questions",
"message": "Must contain at least one question"
}
]
}
}
} invalid_question_type
Unsupported question type
Resource errors
not_found
Resource not found
answer_not_found
Answer not found
workspace_not_found
Workspace not found