Handle API errors
Read RFC 9457 problem details, choose a retry policy, and trace a failed request.
Gridstate returns RFC 9457 problem details with a stable error code and request ID. Use those fields to decide whether to change or retry the request.
Read the problem response
Errors use the application/problem+json content type:
{
"type": "/v1/error-codes/invalid_query",
"title": "Invalid query",
"status": 400,
"code": "invalid_query",
"requestId": "req_1234567890123",
"docUrl": "/v1/error-codes/invalid_query"
}Request docUrl without a credential to retrieve remediation for the returned code.
Choose an action from the status
Use the HTTP status and stable code together:
| Status | Meaning | Action |
|---|---|---|
400 | Malformed request, unsupported query, or unsupported API version | Correct the request |
401 | Missing or invalid credential | Replace the credential |
403 | Valid credential without the required scope | Use a correctly scoped key |
404 | Missing or intentionally concealed resource | Verify the resource ID and tenant |
409 | State or idempotency conflict | Reuse the original request or create a new key |
422 | Semantically invalid request | Correct the submitted values |
429 | Rate or concurrency limit exceeded | Wait for the returned retry interval |
503 | Temporary dependency or release failure | Retry with bounded backoff |
Retry only temporary failures
Retry 429 and 503 with bounded exponential backoff and jitter. Do not retry other 4xx responses without changing the request.
Keep the request ID
Log requestId with the operation that failed. Gridstate support uses it to trace one request without exposing your API key or request body.