Handle retries without starting duplicate agent work.

Idempotency

• Generate a fresh UUID for each new runtime task.
• Reuse the same key only for transport retries of that same request.
• If a stream drops after response.created, recover from the session instead of sending a new task.

HTTP errors

A failure answers with a JSON envelope under error, carrying the protocol's own type and code alongside a message you can show. Match on code rather than on the message, which is written for a person.

One 502 is worth naming: store_write_failed, "The record could not be saved. Try again in a moment." The work may have run, so recover the session rather than sending the task again.

400

invalid_request_error / invalid_input

401

authentication_error / invalid_credential

402

billing_error / payment_required. A task refused for want of credit.

403

permission_error / insufficient_scope

404

invalid_request_error / not_found

409

invalid_request_error / conflict

413

invalid_request_error / file_too_large

429

rate_limit_error / rate_limited

500, 502, 503, 504

server_error / internal_error, upstream_error, unavailable, timeout

A body that does not validate

A request whose body fails validation answers 422. The message names the field that failed, param is its dotted path, and detail lists every failure rather than only the first, so a form can mark all of its bad fields in one round trip.

The response never echoes the request body back, so a field you sent does not reappear in logs or in an error surfaced to a user.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "metadata.environment: Input should be a valid string",
    "param": "metadata.environment",
    "detail": [
      {"loc": ["body", "metadata", "environment"],
       "msg": "Input should be a valid string",
       "type": "string_type"}
    ]
  }
}