Errors and Retries

Error Envelope

Failed requests return a non-2xx HTTP status and an error envelope.

{
  "success": false,
  "error": "Unauthorized",
  "message": "API key required for public endpoints"
}

Use the HTTP status for control flow and message for logs or operator-facing diagnostics.

Retry Policy

Response	Retry?	Action
`400`	No	Fix the payload or required parameter.
`401`	No	Check, reactivate, or replace the API key.
`404`	Usually no	Refresh the VisaFlo ID or confirm workspace ownership.
`429`	Yes	Exponential backoff with jitter.
`5xx`	Yes	Retry with bounded exponential backoff.

Avoid Duplicates

The public API does not accept a generic idempotency-key header. Build idempotency in your integration:

Store the VisaFlo ID returned from every successful create.
Search by a stable field, such as email or case number, before retrying a create.
Use the stored VisaFlo ID for files, tasks, notes, and updates.
Log the source event ID beside the VisaFlo ID so operators can reconcile retries.

Rate Limits

VisaFlo applies rate limiting to workspace API routes. On 429, pause the affected job and retry later. Do not fan out retries across many workers, because that prolongs the limit window.

Safe Logging

Log request IDs, VisaFlo IDs, status codes, and response messages. Do not log API keys or raw immigration documents. Redact emails and personally identifying data where your logging policy requires it.

Authentication Endpoint directory

⌘I

​Error Envelope

​Retry Policy

​Avoid Duplicates

​Rate Limits

​Safe Logging

Error Envelope

Retry Policy

Avoid Duplicates

Rate Limits

Safe Logging