API errors and rate limits
Errors are JSON. A single problem is { "detail": "…" }. A field problem is an object of field names to a list of messages, for example { "country": ["…"] }.
Rate limit
Each API key may make 120 requests a minute. The counter is per key. A session that is not using a key is not counted against it. Past the limit the response is 429 and the body is the framework throttle message, including how soon another request will be accepted.
Status codes
| Status | When |
|---|---|
| 400 | The body failed validation, or the action is not allowed in the current state (for example deleting an assessment that is no longer a draft). |
| 401 | The header is malformed, the key is unknown, revoked or expired, the plan no longer includes the API, or the member who created the key has left. |
| 403 | The key is aimed at another organization, a read key attempted a write, or the creator's role cannot do that action. |
| 404 | The record is not in this organization. Another tenant's id is a 404, not a 403 that would confirm it exists. |
| 402 | The plan does not include the feature, or a seat or vendor limit is already reached. The body includes code (feature_not_in_plan or plan_limit_reached) and the plan or the counts. |
| 409 | A report was requested for an assessment that has no score yet. |
| 429 | The key exceeded 120 requests in the current minute. |
| 503 | A dependency is not configured or did not respond. Screening, discovery and questionnaire drafting fail this way rather than returning an empty success. Screening still records a run with status FAILED. |
Examples
A read key that tries to create a vendor:
{ "detail": "This is a read-only key." }A feature the plan does not include:
{
"detail": "Audit-ready PDF report is included from the Starter plan. Upgrade to use it.",
"code": "feature_not_in_plan",
"feature": "pdf_report",
"required_plan": "STARTER"
}The sentence names the cheapest plan that has the feature. required_plan is that plan's code.