Errors
Interpret standard API error envelopes and respond correctly to validation, authentication, authorization, conflict, and quota failures.
ReportPlane APIs return JSON errors using a standard envelope:
{
"error": true,
"message": "human-readable explanation"
}
Successful responses use error: false and place the resource or result in data.
HTTP status guide
| Status | Meaning | Recommended action |
|---|---|---|
400 | Invalid request, model, filter, or query plan | Correct the request; do not blindly retry |
401 | Authentication failed | Check or rotate the credential |
403 | Identity is valid but policy forbids the action | Review role, resource scope, CIDR, or binding |
404 | Route/resource unavailable | Check origin, path, ID, enabled feature, and project |
409 | Current state conflicts with the action | Refresh state or complete the required lifecycle step |
413 | Request exceeds a body limit | Reduce or split the payload |
429 | Connection, rate, or quota limit | Back off and inspect limits |
500+ | Server or dependency failure | Retry safely with bounded backoff and retain correlation context |
Validation messages
Validation messages identify missing names/IDs, invalid field types, incompatible filters, unavailable model access, or malformed credentials. Treat them as part of the current API behavior, but avoid parsing arbitrary prose as a stable machine code unless a documented field provides one.
Safe retries
Retry idempotent reads and requests that the API clearly did not accept. For ingest, a 202 means the batch was accepted; resending it may create a second record unless your data model and application provide their own deduplication strategy.