Substy Errors
Diagnose failed requests and decide when a retry is appropriate.
Errors use a consistent JSON envelope:
{
"error": {
"code": "BAD_REQUEST",
"message": "Correct the listed fields using the endpoint schema.",
"requestId": "request-identifier",
"fields": [{ "path": "limit", "reason": "Use a valid value." }]
}
}Additional context can include operationId, requiredAccess, reason, or retryAfterSeconds. These fields are present only when relevant. Keep the request identifier when reporting an issue.
| HTTP status | Meaning | Next step |
|---|---|---|
| 400 | Invalid input | Correct the indicated fields. |
| 401 | Authentication failed | Check the key and its expiration or revocation. |
| 403 | Access denied | Check agency, category grants, role, and creator access. |
| 404 | Resource unavailable | Verify the resource identifier and access. |
| 409 | Conflict or operation state | Read the message and inspect any operation receipt. |
| 412 | Required precondition missing | Complete the prerequisite described in the error. |
| 413 | Request body too large | Reduce the payload. |
| 429 | Rate or concurrency limit | Respect the Retry-After header. |
| 503 | Dependency or service unavailable | Retry reads with backoff; inspect write receipts first. |
Other domain-specific errors can occur. Treat the HTTP status as the broad category and the error body as the actionable explanation.
Uncertain outcomes
A network timeout does not prove a write failed. If you received an operationId, check its status before resubmitting. If you did not receive a receipt, reconcile the resulting resource before retrying a consequential action.
Do not include keys, fan conversation text, or connection credentials in logs or support reports. Share the request identifier and the non-sensitive error code instead.