API errors and responses
Treat transport status, response payloads, and asynchronous workflow state as separate signals. A request can be accepted by the API while the requested platform operation later fails validation, authorization, or execution.
HTTP responses
REST controllers use normal HTTP status codes:
200 OK: the request completed and returned a response body.201 Created: a resource was created. the response may include its representation and location.202 Accepted: work was queued and will complete asynchronously.204 No Content: the request completed without a response body.400 Bad Request: the body, route identifier, or input values are invalid. Many validation failures useProblemDetails.401 Unauthorized: the bearer token is missing, expired, or invalid.403 Forbidden: the caller is authenticated but lacks the required team, project, component, or operation permission.404 Not Found: the resource does not exist or is not visible in the caller’s authorized context.
Example ProblemDetails shape:
{
"title": "Invalid payload",
"detail": "Request body is required.",
"status": 400
}
The exact fields and messages vary by controller and validation path. Do not build automation around human-readable detail text alone.
GraphQL responses
GraphQL commonly returns an HTTP response containing data, errors, or both:
{
"data": null,
"errors": [
{
"message": "The caller is not authorized to perform this operation."
}
]
}
Always inspect errors, even when the HTTP request succeeds. For mutation payloads, also inspect the returned success or failure fields exposed by that payload and follow the workflow state for asynchronous operations.
Retry guidance
Retry only failures that are safe for the operation and appropriate for the status. Use bounded exponential backoff for transient transport or service failures. Avoid blindly retrying mutations that may have been accepted. first query the resource or workflow state when the operation supports it.