Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsErrors and rate limits
Search the full API reference Esc to close

Errors and rate limits

Understand the response envelope, recover from errors, and retry carefully.

Get support

Read the error envelope

An error includes a machine-readable error.code, a human-readable error.message, optional details, and a request ID for tracing.

JSON · illustrative error
{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action.",
    "details": null
  },
  "meta": {
    "request_id": "example-request-id"
  }
}

Respond to the status code

StatusMeaningNext step
400Validation errorCheck parameters and body against the schema.
401UnauthenticatedCheck or renew the credential and confirm the environment.
403Permission deniedCheck permissions, facility scope, and IP restrictions.
404Not foundCheck the resource ID and authorized scope.
409Business conflictRead the message and reason code; resolve the conflict.
429Rate limitedHonor Retry-After when present, then back off.
503Temporary failureRead the reason code before deciding to retry.

Respect rate limits

Limits vary by endpoint and operation. API-key requests are bucketed per key, per route. Do not assume one global requests-per-minute limit for the whole API.

On 429, use Retry-After when supplied. Use bounded exponential backoff with jitter and avoid parallel retry bursts.

Retry writes deliberately

A network timeout does not prove a write failed. Check whether the operation completed before sending it again. Where an endpoint documents Idempotency-Key, reuse the same key only for the same logical operation and unchanged payload.

Idempotency is endpoint-specific. Do not add an undocumented header and assume a payment or resource creation becomes safe to repeat.

Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Errors and rate limits | Facily Developers