Skip to main content
Most application errors return FastAPI-style JSON with a top-level detail field: 
{
  "detail": "Human-readable description of what went wrong"
}
Validation errors use a structured detail array: 
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "date"],
      "msg": "Field required",
      "input": null
    }
  ]
}
Usage-limit responses on billable market endpoints add extra fields: 
{
  "detail": "API usage limit reached. You've used 50/50 calls this month.",
  "error_code": "USAGE_LIMIT_EXCEEDED",
  "current_usage": 50,
  "limit": 50,
  "tier": "free",
  "upgrade_url": "/pricing"
}

​
Status Codes

Status CodeDescription
200Success
400Bad Request — missing or invalid parameters
401Unauthorized — invalid or missing API key
404Not Found — resource does not exist
422Validation Error — required parameters are missing or malformed at the framework level
429Too Many Requests — plan usage limit reached on a billable market endpoint
500Internal Server Error — something went wrong on our end

​
Error Examples

​
401 Unauthorized

Returned when the API key is missing or invalid. 
{
  "detail": "Invalid API key"
}

​
400 Bad Request

Returned when required parameters are missing or malformed. 
{
  "detail": "start_timestamp must be less than or equal to end_timestamp"
}

​
422 Validation Error

Returned when FastAPI rejects the request before endpoint logic runs. 
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "condition_id"],
      "msg": "Field required",
      "input": null
    }
  ]
}

​
429 Too Many Requests

Returned when the current plan’s monthly market-endpoint allowance has been exhausted. 
{
  "detail": "API usage limit reached. You've used 50/50 calls this month.",
  "error_code": "USAGE_LIMIT_EXCEEDED",
  "current_usage": 50,
  "limit": 50,
  "tier": "free",
  "upgrade_url": "/pricing"
}

​
500 Internal Server Error

Returned when an unexpected server-side error occurs. If this persists, contact founders@entityml.com. 
{
  "detail": "Internal server error: <message>"
}