| Setup | The client refuses, with PeelError code invalid_option and before any request, an API key that does not start with sk_urlapi_, a base URL that is not https:// (plain http:// only for localhost, 127.0.0.1 and [::1]), a timeout that is zero, negative or not a finite number (on the client or on one call; TypeScript also caps it at 2,147,483,647 ms), and a per-call Authorization or X-API-Key header. The key is checked again whenever the auth header is built, so the client and the server agree on whether a call is keyed. The SDKs take Peel API keys only; MCP OAuth tokens are for MCP clients. |
| Errors | A failed request raises PeelError with status, code, message, retryable, retry (same_key, new_key, fix_request or never), the action outcome when known, docs_url (docsUrl), details, the request id from x-request-id and the Retry-After wait. Network failures, timeouts and cut-off bodies raise it with code transport_error, timeout or body_read_failed. An endpoint call (call, marketplaceCall and the generated callApiEndpoint and callMarketplaceEndpoint, or their Python names) also raises it when the call ran but its result says status: "error"; batch keeps per-item errors in its result. See Errors. |
| Timeouts | timeoutMs (TypeScript, rounded up to whole milliseconds) or timeout in seconds (Python) bounds the whole request, including a body that arrives slowly. In Python the connect and each socket read get the time left, and a timeout closes the connection. A write that timed out before its request was fully sent reports action_outcome not_committed; after that, unknown. Python cannot interrupt the DNS lookup, so a slow resolver can add to the time. |
| Retries | Reads (GET, HEAD) retry errors with retryable: true, at most twice by default, after the Retry-After wait. A write retries only when it sent an Idempotency-Key that the operation enforces (which needs an API key), with the same key, or when the error says nothing was committed. Otherwise it raises at once, and a retryable, server, network or cut-off failure reports the outcome as unknown. Once any attempt may have reached the server, the outcome stays unknown, whatever later attempts return. retry: "new_key" is never replayed for you. A wait over 30 seconds, such as a daily limit, raises at once. |
| Redirects | Both clients raise invalid_path before sending when a request path would leave the base URL’s origin, such as .other.test/resource. Python never follows a redirect: a 3xx raises PeelError with that status. TypeScript follows a read’s 301, 302, 303, 307 and 308 within the same origin, up to 20 hops, and raises PeelError cross_origin_redirect for one to another origin, so the key and session headers never reach it. Any other 3xx, such as 304, raises with its status. A write never follows a redirect: TypeScript raises write_redirected for a redirect or an unreadable Location, and the write is not sent again. |
| Idempotency | Operations that accept Idempotency-Key get one generated per call, and a retry reuses it. Pass your own to make a retry across processes safe. |
| Waiting | wait, and build with wait, keep one deadline: every request inside gets the smaller of its normal timeout and the time left, so a stalled poll times out and the next poll runs, and they never start a long poll that could outlast the deadline. Near the deadline they read the status instead and return the same shape, with waited and timed_out false. A finished build that arrives is always returned. If the deadline passes while the build is still running, they return the last answer with timed_out true. They raise when the server asks for a longer wait than is left. wait can return up to one request’s network margin after the deadline. |
| Pages | paginate follows next_cursor: peel.paginate(peel.listRuns, { query: { limit: 50 } }) in TypeScript, peel.paginate(peel.list_runs, limit=50) in Python. A cursor seen twice raises. |
| Batches | batch(apiId, endpoint, inputs) calls one endpoint for up to 100 inputs. See Batches. |
| OAuth and MCP | The MCP transport and GET /oauth/authorize return the raw response (status, headers and body text) without raising or following redirects, because their meaning depends on the status, such as 202 for an MCP notification or the 302 from authorize. The other OAuth operations, such as the token endpoint, return parsed JSON and raise on errors. |
| Teams | An API key always acts on its own account. Operations that only accept a signed-in Peel session are not in the SDKs: team invites, joining, listing or leaving accounts, and OAuth consent approval (POST /oauth/authorize). |