v1.0.1
REST APIv1.0.0
Errors & Status Codes
Structured error response envelope, HTTP status code meanings, and request correlation IDs.
BehaviorSim API formats all client and server errors into a predictable JSON envelope matching application-level exceptions.
Standard Error Envelope
error_response.json
{
"error": {
"message": "Missing or invalid authentication credentials.",
"status_code": 401,
"details": {},
"request_id": "req_8f7e6d5c4b3a2"
}
}HTTP Status Codes
| Code | Meaning | Cause / Example |
|---|---|---|
| 400 | Bad Request | Interaction count exceeds per-request limit (1,000) |
| 401 | Unauthorized | Invalid or missing API key or session cookie |
| 403 | Forbidden | Monthly interactions quota exhausted or inactive user |
| 404 | Not Found | Preset name or API key ID does not exist |
| 409 | Conflict | Active API key count limit (1 on Free tier) exceeded |
| 422 | Unprocessable Entity | Request parameters failed schema validation (type mismatch) |
| 429 | Too Many Requests | Sliding-window rate limit (5 req/min) exceeded; see Retry-After header |
| 503 | Service Unavailable | Database connectivity lost during readiness check |
Validation Errors (422)
When input validation fails, details contains an array specifying the exact parameter location:
validation_error.json
{
"error": {
"message": "Invalid request parameters.",
"status_code": 422,
"details": {
"errors": [
{
"loc": ["body", "num_interactions"],
"msg": "Input should be greater than or equal to 1",
"type": "greater_than_equal"
}
]
},
"request_id": "req_10101"
}
}Reporting Issues with Request IDs
Always copy the request_id from the error payload or the X-Request-ID header when opening an issue on GitHub.