FARPY Public API V1
Predictable errors and retries
Use HTTP status, stable error codes, retry timing and idempotency keys to operate reliable FARPY integrations.
Production flow
capabilities pricing upload submit status download receipt proof
HTTP status and recovery map
- HTTP 400: malformed request. Do not retry until the request is corrected.
- HTTP 401: missing or invalid API key. Do not retry until authentication is corrected.
- HTTP 403: the key or workspace is not allowed to perform the action.
- HTTP 404: the requested upload, render, receipt, proof, or artifact was not found.
- HTTP 409: conflict or idempotency mismatch. Reuse the original idempotency key and request body.
- HTTP 413: upload exceeds the 100 MiB payload limit. Reduce the file before retrying.
- HTTP 422: validation failed. Correct the supplied fields before retrying.
- HTTP 429: rate limit reached. Retry only after Retry-After or retry_after_seconds.
- HTTP 500: unexpected server failure. Retry with bounded exponential backoff when error.retryable is true.
- HTTP 503: service temporarily unavailable. Retry with bounded exponential backoff.
Terminal jobs and billing
- render.failed is terminal. Failed renders cost $0.
- render.cancelled is terminal.
- Work cancelled before completion is not charged as completed output.
- Do not retry a terminal job blindly. Submit corrected work with a new idempotency key.
API properties
- API-key authentication
- 100 MiB upload limit
- Idempotent submission support
- 60 requests per minute plus burst capacity
- Cancellation before worker claim
- Signed terminal webhooks
- Receipts and proof artifacts
- Error responses include error.code and error.message
- error.retryable states whether the same request may be retried.
- error.suggested_action gives the next corrective action.
- Rate-limit responses include error.retry_after_seconds and Retry-After.
- error.request_id provides a request identifier for diagnostics.
- Machine-readable OpenAPI 3.1 specification
Agent retry policy
- Retry HTTP 429 only after Retry-After or retry_after_seconds.
- Retry temporary network, HTTP 502 and HTTP 504 failures with bounded exponential backoff.
- Reuse the same idempotency key after an uncertain submission result.
- Stop on authentication, validation, balance and terminal job failures until the cause is corrected.
- Preserve the job ID, HTTP status, error.code, error.message and error.request_id for diagnostics.
Start here
curl -sS https://farpy.com/v1/capabilities \ -H "Authorization: Bearer $FARPY_API_KEY"
API overview · Quickstart · Agent integration guide · Webhook delivery guide · Developer error reference · OpenAPI · Pricing · Status · Proof