Errors - FastCAC Developers

Errors use conventional HTTP statuses and always have the same body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "registration_incomplete",
    "message": "Still needed: line_of_business, business.email, business.address.street_number, business.address.street, business.address.city, business.address.state, proprietors.",
    "param": "line_of_business",
    "request_id": "req_7AfesouxYdjXTgJptXr3ykSU"
  }
}

Field	Meaning
`type`	The broad class: `invalid_request_error`, `authentication_error`, `permission_error`, `idempotency_error`, `rate_limit_error` or `api_error`.
`code`	Specific and stable. Branch on this.
`message`	A description for developers. It may change; don’t parse it.
`param`	The parameter at fault, as a path like `proprietors[0].nin`. Point your form at it.
`request_id`	Also in the `FastCAC-Request-Id` response header. Quote it when you contact support.

Codes

HTTP	`code`	Meaning
400	`parameter_invalid`	A value is missing, malformed or not allowed.
400	`registration_incomplete`	Required fields or documents are missing; `param` is the first.
400	`field_not_queried`	While queried, only the queried fields can change.
400	`query_unresolved`	Some queried fields haven’t been fixed yet.
400	`file_too_large`, `file_empty`	The upload is over 5 MB or empty.
400	`idempotency_key_too_long`	`Idempotency-Key` is over 255 characters.
400	`browser_requests_not_allowed`	Call the API from your server, not a browser.
400	`url_invalid`, `url_not_allowed`, `url_not_public`, `url_unresolvable`, `event_type_unknown`	A webhook endpoint can’t be saved as given.
401	`api_key_missing`, `invalid_api_key`	See Authentication.
403	`live_mode_unavailable`	Live registrations aren’t open for your organization yet.
404	`resource_missing`	No such object for this key’s organization and mode.
409	`invalid_state`	The registration’s status doesn’t allow this.
409	`registration_locked`	The registration can’t be changed in its current status.
409	`certificate_not_ready`, `status_report_not_ready`	Wait for approval.
409	`idempotency_key_reused`, `idempotency_request_in_progress`	See Idempotency.
409	`endpoint_limit`	You already have 10 webhook endpoints in this mode.
429	`rate_limited`, `too_many_failed_attempts`	See Rate limits.
500	`internal_error`	Something went wrong on our side. Safe to retry with the same `Idempotency-Key`.
503	`name_check_unavailable`, `webhooks_unavailable`	A dependency is down. Retry shortly.

New codes may be added. Handle unknown codes by their HTTP status and type.

Retrying

Retry 429, 500 and 503 with exponential backoff, and send an Idempotency-Key on every POST so a retry can never act twice. Don’t retry other 4xx errors unchanged; fix the request.