Prompting
Text Prompting
Using Files
We currently support PNG (.png), JPEG (.jpeg and .jpg), WEBP (.webp), non-animated GIF (.gif) and PDFs (.pdf) as files.
Using system instructions
Use the instructions parameter to provide specific guidelines for the AI to follow when responding to the main prompt.
Handling prompt failures
prompt raises AIPromptError when the HTTP request is unsuccessful or a successful HTTP response cannot be decoded as JSON. The exception exposes status_code, category, and code. Its message deliberately omits the response body, which may contain sensitive document data.
The categories describe the response, not necessarily its underlying cause:
| Category | Meaning |
|---|---|
quota_exceeded | HTTP 403 with the service's quota_exceeded code. Resolve the consumption limit before retrying. |
rate_limited | HTTP 429. The request was rate-limited. |
server_error | HTTP 5xx. This can represent service unavailability or another server-side failure. |
http_error | Another unsuccessful HTTP status. Inspect status_code; do not assume a consumption limit from a generic 403. |
invalid_response | A successful HTTP status with a body that could not be decoded as JSON. |
code is quota_exceeded only for a recognized consumption-limit response; otherwise it is None. Other prompt failures, such as invalid structured-output arguments, can still raise other exceptions. Transport failures remain Requests exceptions.
A server error does not prove the failure is transient, and a timeout does not prove the request was never processed. If your workflow retries a known transient failure, use bounded attempts and backoff, and make document processing and downstream writes idempotent. Do not mark a task complete merely because a prompt failed or create additional tasks on every retry. This error handling does not add automatic retries.
These attributes require an SDK version containing the prompt-error fix; older installed versions may raise generic exceptions or JSON decoding errors instead.