Errors, Limits, and Pagination
This reference applies to the FormKiQ v1.19.2 API. Limits come from the operation, workspace configuration, installed modules, and AWS account quotas; there is no single deployment-wide requests-per-second entitlement.
Error responses
Always inspect the HTTP status before parsing a success model. Validation errors can use this schema:
{"errors":[{"key":"path","error":"A valid path is required"}]}
Other failures, including gateway and authentication failures, can return a message field instead. Some failures have a non-JSON or empty body. The message above is illustrative, not a stable error code. Preserve status, request ID, operation, and a bounded/redacted body in diagnostics; do not log bearer tokens, API keys, signed URLs, or document content.
| Status | Typical meaning | Client action |
|---|---|---|
400 | Invalid body, unsupported value, missing field, or configured restriction. | Fix the request; inspect errors or message. |
401 | Missing/expired credential or an authorization failure. Folder content denial can also return this status. | Check endpoint, token issuer/type/expiry, and permissions. Do not blindly refresh forever. |
403 | Forbidden by a service, role, policy, or storage control. | Check workspace, folder/policy grants, AWS IAM, and the operation's dedicated permission. |
404 | Resource or route not found, possibly in another site. | Confirm ID, exact path/case, siteId, edition, and installed operation. |
409 | State conflict, for example a resolved review. | Refresh state; do not repeat a decision assuming it failed. |
413 | Payload too large for a service boundary. | Use a supported direct-to-S3 upload, or reduce the request. |
429 | Throttling or an operation-specific refusal. A disabled webhook also uses 429. | Inspect the reason; only retry transient limits. |
5xx | Gateway, backend, dependency, or transient service failure. | Retry safe/idempotent work with bounded backoff; inspect logs/DLQ for persistent failures. |
A successful upload request or processing response does not mean OCR, indexing, extraction, review, or email delivery is complete. Check the corresponding action/result record. A timeout can occur after a mutation succeeded; reconcile before retrying creation or a destructive operation.
Upload size and transfer paths
Inline POST /documents sends content through API Gateway and Lambda. Base64 encoding adds roughly one third to the content size, plus JSON and the invocation envelope. The effective safe body size is therefore lower than the raw file size limit of either service. API Gateway HTTP APIs have a 10 MB payload ceiling; Lambda synchronous invocations have a 6 MB request/response ceiling. These are service ceilings, not a promise that a 6 MB document fits an inline request.
For ordinary file uploads, request a presigned URL and send the file bytes directly to S3. The request can include contentLength in bytes; it is required when the site's MaxContentLengthBytes restriction is configured.
curl -G "${HTTP_API_URL}/documents/upload" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
--data-urlencode "siteId=${SITE_ID}" \
--data-urlencode 'path=invoices/invoice-1001.pdf' \
--data-urlencode 'contentLength=2450'
A response includes documentId, url, and, where required, storage headers. PUT the exact file bytes to url, sending all returned headers unchanged. Do not send the FormKiQ bearer token to S3. The document may be visible before content processing completes. See Add Documents.
The v1.19.2 upload endpoint issues a single S3 PUT URL. AWS documents a 5 GB maximum for a single PUT; a workspace restriction or processing service can impose a lower limit. It does not expose an S3 multipart initiation/part/completion contract. Splitting a file and repeatedly using the same URL overwrites the object; it does not assemble the parts. For files beyond the single-request storage limit or a deployment's tested processing limits, agree a supported import/multipart path with FormKiQ. Do not infer FormKiQ processing support from S3's maximum multipart object size.
The requested upload duration is in hours (48 by default in this handler), but signing credentials and S3 policy can make the effective URL lifetime shorter. Request a new URL after expiry rather than changing signed parameters. OCR, document generation, preview, email, and AI models have their own file/page/context limits.
Workspace and AWS limits
Inspect workspace General & limits and its API configuration for maximum document count, total storage, webhook count, accepted file types, and content length. Do not confuse a total-storage quota with a per-file quota. A batch request can consume more than one document slot.
Check AWS Service Quotas in the actual account/region for API Gateway, Lambda concurrency, DynamoDB, Textract, Bedrock, SES, and search services. Rate-limit callers and queue bursts. Model-specific limits, region availability, and licensed processing capabilities must be checked separately.
Throttling and retries
Use exponential backoff with jitter, a cap, and an overall deadline. Honor Retry-After when returned. Retry reads and explicitly idempotent work; do not assume arbitrary POSTs have an idempotency key. Webhooks document their own Idempotency-Key behavior.
A 429 webhook is disabled will not be fixed by waiting. A private webhook's off/on mode change in v1.19.2 also needs deliberate handling. Inspect application errors before classifying every 429 as capacity throttling.
Pagination
Most list/search operations use limit and an opaque next string. The shared limit parameter defaults to 10, but individual operations can differ. There is no universal maximum page size guaranteed for all endpoints.
- Send the first request without
next. - Process that page's collection.
- If a nonempty
nextis returned, repeat the same operation, site, and filters with that token. - Stop only when no continuation token remains. A short or empty page alone does not prove completion.
URL-encode query tokens once; do not decode, inspect, concatenate, or manufacture them. For a query-parameter operation:
curl -G "${HTTP_API_URL}/documents" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
--data-urlencode "siteId=${SITE_ID}" \
--data-urlencode 'limit=10' \
--data-urlencode "next=${NEXT_TOKEN}"
For search operations, follow the operation's specified token location and preserve the original search body. The cursor is not a stable page number or a snapshot of a changing repository. Deduplicate by stable IDs, persist checkpoints for long jobs, and reconcile documents changed during enumeration. Do not calculate a total count from the first page's length.