> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fidel80.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Troubleshooting

> Common Fidel80 integration errors and how to troubleshoot them.

This page covers common issues developers may encounter when integrating with Fidel80.

## Authentication required

If an API request is rejected because authentication is required:

* confirm that the `Authorization` header is included,
* confirm that the value uses `Bearer`,
* confirm that the API key begins with `fidel80_`.

## Invalid or expired API key

Check that:

* the key has not been revoked,
* the key has not expired,
* the correct key value is being used.

If necessary, create a new API key from **Developers → API authentication**.

## Workflow not found or not accessible

Confirm that the workflow ID:

* exists,
* belongs to the same organization as the authenticated API key,
* is the workflow you intended to use.

## Workflow is not active

Verification tokens can only be generated for an active workflow.

Confirm the workflow status in Fidel80 before retrying the request.

## Invalid workflow version

The workflow version must belong to the selected workflow.

Check both `workflowId` and `workflowVersionId` before submitting the mutation.

## Subscription or usage limit

Fidel80 may prevent a verification from being generated when subscription or usage limits apply.

If authentication and workflow configuration are correct but the request is still rejected, check the organization subscription and verification usage status.

## Invalid verification link

A verification link may no longer be valid if the token is:

* expired,
* completed,
* cancelled,
* invalid.

Generate a new verification token when a fresh verification session is required.

## Webhook delivery issues

If your webhook endpoint is not receiving completion events:

* confirm the webhook is enabled,
* confirm the destination URL is correct,
* confirm the endpoint accepts HTTP `POST`,
* confirm the endpoint accepts JSON,
* confirm the endpoint is reachable from outside your local network,
* open **Developers → Webhook logs** and inspect the delivery status and attempts.

Fidel80 retries connection errors, timeouts, HTTP `408`, HTTP `429`, and HTTP `5xx` responses.

The verified retry schedule is:

1. initial attempt immediately,
2. second attempt after 60 seconds,
3. final attempt after another 300 seconds.

Other HTTP `4xx` responses are not retried.

If signature verification is failing:

* confirm you are using the correct webhook signing secret,
* read `X-Fidel80-Timestamp`,
* read `X-Fidel80-Signature`,
* calculate HMAC-SHA256 over `{timestamp}.{raw-request-body}`,
* ensure the calculated signature uses the `sha256=<hex-digest>` format,
* verify the exact raw body rather than re-serialized JSON.

See [Webhooks](https://docs.fidel80.com/guides/webhooks.md) for the complete signing and retry behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.