API Status Codes

This page lists the HTTP status codes used by the APIs referenced in this documentation, along with practical explanations.

Status Code	Meaning	Description (When it is returned / what it means / what the developer should do)
200	OK	Successful response. The request was processed successfully, and the response body contains the expected data, such as an Assistant or Workflow output, list, or detail. User: Validate the response schema and check the expected fields.
204	No Content	Successful response with no content. This is commonly returned for deletion or cancellation operations, or when an update succeeds but there is no data to return. User: Do not expect a response body. Handle the successful status accordingly in the UI or workflow.
400	Bad Request	Invalid request. Returned for malformed JSON, missing required fields, incorrect types or formats, invalid query parameters, or inconsistent field combinations. User: Correct the request payload and parameters. Clearly display the returned error details, including field-level messages, to the user.
401	Unauthorized	Authentication is missing or invalid. The token may be missing, invalid, or expired. User: Check the Authorization header, refresh the token or require the user to sign in again, and make sure you are using the correct key or token for the correct environment (env).
403	Forbidden	Access denied. Authentication was successful, but you do not have permission to access the requested resource or operation due to role, scope, or tenant restrictions. User: Try again with the correct role or scope, check project and organization permissions, and match the required permissions for the endpoint with the documentation.
404	Not Found	The resource or endpoint was not found. This may occur when the URL or route is incorrect, the ID is invalid, the base URL is wrong, or the incorrect environment is being used. User: Check the endpoint path, resource ID, and base URL. Make sure the resource has actually been created.
405	Method Not Allowed	The HTTP method is not supported. The endpoint exists, but the method being used is incorrect, such as using GET instead of POST. User: Use the correct method and verify the endpoint-method mapping in the client or SDK. Check the Allow header when necessary.
406	Not Acceptable	The requested response format cannot be produced. The client’s Accept header may request an unsupported format. User: In most cases, use Accept: application/json and correct the content negotiation settings.
408	Request Timeout	The request timed out. The server did not receive the complete request or could not begin processing it within the allowed time. This may be caused by a slow network, a long-running request, or upload delays. User: Review timeout settings, retry the request, reduce the payload size, or split the operation into smaller parts. For long-running operations, use the platform’s recommended asynchronous model, such as a job and polling approach, when available.
413	Payload Too Large	The request body is too large. Returned when a large file or JSON payload exceeds the configured limits. User: Reduce the payload size, split the file into chunks or use multipart upload, check the limits, and use the recommended upload method.
415	Unsupported Media Type	The Content-Type is incorrect. The server cannot process the submitted data format, such as when JSON is expected but a different content type is sent. User: Use Content-Type: application/json or the format specified in the documentation. Make sure the body format matches the header.
429	Too Many Requests	The rate limit or quota has been exceeded. Requests are restricted because they are sent too frequently or because plan limits have been reached. User: Follow the Retry-After value when provided, implement retries with exponential backoff, throttle requests, use batching or caching, and increase the plan or quota when necessary.
431	Request Header Fields Too Large	The request headers are too large. This may be caused by oversized cookies, long tokens, or unnecessarily large custom headers. User: Reduce header sizes, clear cookies, remove unnecessary headers, and send large data in the request body or store it as server-side state instead of placing it in headers.
499	Client Closed Request	The client, application, browser, gateway, or proxy closed the connection before receiving the response. This usually occurs when the user leaves the page, the request is cancelled, the client reaches its timeout, or the connection is interrupted. User: Check client timeout values, use an asynchronous model such as jobs and polling for long-running operations, design the request to be idempotent and apply safe retries, add retry and backoff mechanisms for network interruptions, reduce the request size when possible, and correlate the issue with log entries such as “client cancelled” or “aborted.”
500	Internal Server Error	An unexpected server-side error occurred. This is commonly caused by an unhandled exception, incorrect configuration, or dependency failure. User: Match the request ID or trace ID with the logs when available, retry the same request in a controlled manner, and contact the support team with the error details if the problem persists.
503	Service Unavailable	The service is temporarily unavailable. This may be caused by maintenance, excessive load, or a downstream service issue. User: Retry after a short delay using backoff, add fallback or graceful degradation for critical flows, and check the status or health page when available.
504	Gateway Timeout	The API did not receive a timely response from a dependent service, such as a workflow runner, connector, storage service, or provider, while processing the request. This is usually caused by temporary load or network latency. User: Retry the request, preferably with exponential backoff, review timeout values, and use an asynchronous or polling approach for long-running operations when possible.