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:

/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