Status & Error Codes
Overview
The testing-api is designed to simulate various HTTP response scenarios to help developers validate their application's error handling and state management. By targeting specific endpoints or using query parameters, you can trigger predictable status codes and error payloads.
Global Response Schema
Every error response returned by the API follows a consistent structure to simplify client-side parsing.
{
"status": "error",
"code": 400,
"message": "A human-readable description of the error.",
"error_code": "ERROR_CONSTANT",
"timestamp": "2023-10-27T10:00:00Z"
}
Success Codes (2xx)
These codes indicate that the simulated request was processed successfully. Use these to verify "Happy Path" logic.
| Status Code | Description | Typical Use Case |
| :--- | :--- | :--- |
| 200 OK | The request succeeded. | General GET/PUT success simulation. |
| 201 Created | A new resource was created. | Simulating POST success for entity creation. |
| 204 No Content | The request succeeded but returns no body. | Simulating successful DELETE operations. |
Client Error Codes (4xx)
Use these codes to test how your application handles invalid input, authentication failures, or rate-limiting.
| Status Code | error_code Constant | Description |
| :--- | :--- | :--- |
| 400 Bad Request | INVALID_PAYLOAD | The request was malformed or contained invalid parameters. |
| 401 Unauthorized | AUTH_REQUIRED | Authentication is missing or invalid. |
| 403 Forbidden | INSUFFICIENT_PERMISSIONS | The authenticated user does not have access to the resource. |
| 404 Not Found | RESOURCE_NOT_FOUND | The requested endpoint or resource does not exist. |
| 422 Unprocessable | VALIDATION_FAILED | Semantic errors in the request body (e.g., failed regex). |
| 429 Too Many Requests | RATE_LIMIT_EXCEEDED | The client has exceeded the allowed request threshold. |
Server Error Codes (5xx)
These codes allow you to test your application’s resilience against backend failures and downtime.
| Status Code | error_code Constant | Description |
| :--- | :--- | :--- |
| 500 Internal Error | INTERNAL_SERVER_ERROR | A generic error occurred on the server. |
| 502 Bad Gateway | UPSTREAM_ERROR | The server received an invalid response from an upstream provider. |
| 503 Service Unavailable| MAINTENANCE_MODE | The server is temporarily overloaded or down for maintenance. |
| 504 Gateway Timeout | TIMEOUT | The server did not receive a timely response from the upstream. |
Triggering Specific Responses
To trigger a specific response for testing, append the desired status code to the /status endpoint.
Request Example
curl -X GET "https://api.supervised.ai/testing/status/403" \
-H "Accept: application/json"
Response Example
{
"status": "error",
"code": 403,
"message": "Access Denied: You do not have permission to access this resource.",
"error_code": "INSUFFICIENT_PERMISSIONS",
"timestamp": "2023-10-27T14:20:11Z"
}
Mocking Delays
In addition to status codes, you can simulate network latency by using the delay parameter (in milliseconds). This is useful for testing UI loaders and timeout logic.
Endpoint: /status/{code}?delay={ms}
# Simulates a 500 error with a 3-second delay
curl -X GET "https://api.supervised.ai/testing/status/500?delay=3000"