GloopAPI integration guide
Error handling
Handle errors and retry boundaries.
Determine whether a request was accepted before deciding to retry. Endpoint pages list actual status codes, error envelopes, and representative errors. Different protocols do not necessarily share a JSON structure, and binary success responses may return JSON on failure.
Response decisions
| Signal | Next step |
|---|---|
| 400 / Unsupported field or model | Adjust inputs against the endpoint schema and current capability catalog; do not repeatedly retry unchanged |
| 401 / 403 | Check key expiration, account, IP, model or tool permissions, and quota |
| 402 / Insufficient quota | Add budget or reduce the scope of new requests; continue recovering the original record for existing tasks |
| 404 | Check resource identity, path, and feature switches; do not infer that an unknown submission never executed |
| 409 | Distinguish idempotency conflicts, tasks not ready, quote changes, and referenced resources; handle the specific error |
| 410 | The original resource was deleted or expired; retain billing and idempotency evidence, and do not automatically create another task |
| 429 / 5xx / Network timeout | Back off for rate limits or wait for service recovery, then check acceptance; replay is safe only with an idempotency contract |
Accepted and unknown requests
HTTP 202 means accepted or still pending completion. A tool returning HTTP 200 may also represent a failed task; read status. Acceptance of cancellation is not a cancelled terminal state. An HTTP 200 streaming response may contain error events or terminate abnormally.
For creation timeouts, unknown, and billing_review, retain the original key and query using asynchronous recovery. Retrying a save and generating again are different operations. Save retries may also be unable to recover an expired file source.
Diagnostic information
Record the time, method, path, HTTP status, error code, available request_id, task ID, and business request key. Redact request content and never log API keys or signed URLs. Use the error information returned by the API and your usage records for diagnosis.
Automatic retries must have attempt and time limits. Investigate billable requests unless you can establish that they were not accepted; do not use duplicate submission as the default recovery strategy.
Stable tool error codes
| Machine code | HTTP | Safe handling |
|---|---|---|
| invalid_input | 400 | Check the exact version and input_schema, and correct inputs for the new request |
| invalid_cursor | 400 | Do not construct your own cursor; refresh the first page for a new next_cursor |
| quote_required / budget_required | 400 | Add the quote or cost cap required by the capability fields for a new call |
| quote_expired / quote_stale / invalid_quote | 409 | Recheck and requote only new calls confirmed as not submitted; nonexistent quotes and other users' quotes both return invalid_quote without revealing ownership |
| budget_exceeded | 409 | The new call's budget is insufficient; check maximum_usd and explicitly choose a budget |
| idempotency_conflict | 409 | The request changed under the same request key; retrieve the original complete request and do not automatically resend with a new key |
| tool_service_unavailable | 503 | Infrastructure failure or temporary capability unavailability; recover unknown submissions with the original identity, key, and complete request |
For unknown creation results, first query the original run_id. If there is no run_id, replay using the original API key, original Idempotency-Key, and original complete creation request, including the original quote_id and max_cost_usd. Do not modify an unknown submission because its quote expired or a switch was turned off. Requoting or creating a new request key is only appropriate for a new business operation confirmed as not accepted.