Help
Troubleshooting
Common problems with signing in, sending, documents, payments, links, teams, AI credits and the API, with the error codes you may see and how to fix them.
Most problems have a clear cause and a quick fix. This page is grouped by what you were trying to do. Each entry gives the error code you may see in the app or the API, what it means and what to do.
Every error from the API has the same shape, with a stable code, a plain-English message and a request_id:
{
"error": {
"code": "document_has_payments",
"message": "This invoice has recorded payments and cannot be voided. Create a credit note instead.",
"details": { "document_id": "0193f2b4-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "amount_paid_minor": "50000" },
"request_id": "req_0193f2c0-1d2e-7f30-8a41-5b6c7d8e9f01",
"docs_url": "https://docs.freeinvoiceautomation.com/errors/document_has_payments"
}
}Code against code, not message: messages can be reworded, codes do not change. If you need to contact us, include the request_id. See Errors for the full list.
Signing in
My magic link does not work
Magic links work once and expire after a short time. If you already used the link, or it is old, ask for a new one from the sign-in page. Open the newest email only.
I am locked out after wrong passwords
After too many wrong passwords the account is locked for a while and further attempts are slowed down. Wait, then try again, or sign in with a magic link or reset your password from the sign-in page.
I am asked to sign in again (fresh_signin_required)
Sensitive actions need a recent sign-in: connecting Stripe or another payment method, deleting a business, changing billing, adding a billing card, buying a credit pack, creating an auto_send API key, turning on auto-send for an automation or a store, and deleting the account. Sign in again and retry. API keys cannot perform these actions; use the web app.
I do not see the Apple sign-in button
A sign-in button appears only when that provider is set up on our side. Sign in with Apple is planned for launch, or for the week of 11 January 2027 if it is not ready on launch day. Use another method in the meantime.
I cannot open an account I was invited to (member_deactivated)
The Owner, or someone with team.manage, deactivated you in that account, or the account moved from Team to Free. Ask the Owner to reactivate you. Your own account and any other accounts are not affected.
Sending documents
| Code | Cause | Fix |
|---|---|---|
email_not_verified | The platform mailer needs a verified email address. | Click the verification link we emailed you, or ask for a new one in the app. Your own SMTP works without it. |
quota_exceeded | You used all your platform emails this month (20 on Free, 100 on Team). | Connect your own SMTP (unlimited), or wait for the reset on the first of the month. Your draft is kept. |
platform_mail_paused | The account moved from Team to Free and has already sent 20 or more platform emails this month. | Connect your own SMTP, or wait for next month. |
confirmation_required | A send through the API or MCP needs confirmation. | Check the preview in the response, then send again with "confirm": true. |
document_voided | The document is void. | Voided invoices cannot be sent. Create a new invoice. |
rate_limited | Too many sends in one minute. | Wait for the seconds in Retry-After. |
My client did not get the email
Ask them to check spam or junk. Check the document's activity to see that the email was sent. Platform emails come from "Your Business via Free Invoice Automation" with replies to your business email. You can always Copy link and share the pay link another way, or download the PDF.
I clicked send twice. Did my client get two emails?
No. Sends are protected against duplicates per document, event and channel, so a double click or a retried request sends one email.
My SMTP connection fails (connection_failed)
We test your SMTP details when you save them. Check the host, port, username and password with your email provider. For safety, SMTP servers on private network addresses are refused. See Your own SMTP.
Changing documents
| Code | Cause | Fix |
|---|---|---|
document_not_editable | The document was sent, so it cannot be edited in place. | Make your change as a revision. See Revisions. |
document_has_payments | You tried to void an invoice that has recorded payments. | Issue a credit note instead. See Credit notes. |
document_voided | The action is not allowed on a void document. | Create a new document. |
credit_exceeds_balance | The credit note is larger than what can be credited. | Lower the amount or the lines you credit. |
currency_mismatch | A payment method or amount does not fit the document's currency, for example a QR rail on an invoice that is not in PKR or INR. | Use a method that matches the currency. |
schedule_total_mismatch | Instalments do not add up to the total. | Adjust the parts; the last part absorbs rounding when you let us split it. |
I cannot delete a sent invoice
Sent documents are never deleted, so your records and numbering stay complete. Void the invoice with a reason, or issue a credit note if it has payments. Only drafts can be deleted. See Void and delete.
My business cannot be deleted
A business with sent documents cannot be deleted, because documents and payments are never hard-deleted. Archive the business instead. See Businesses.
Payments
My client paid by card but the invoice still shows unpaid
An invoice is marked paid when Stripe confirms the payment to us, not when the client's browser returns from Checkout. This usually takes moments. If a confirmation is ever lost, a regular check against Stripe corrects it. If it still shows unpaid after a while, check the payment in your Stripe dashboard and contact support with the invoice number.
My client clicked I have paid but the invoice is not paid
That is expected. For bank transfers and QR payments, "I have paid" tells you to check; it does not mark the invoice paid. Confirm the money arrived, then accept the proof or record the payment. See Payment proofs.
The pay page shows no way to pay (rail_not_connected)
The business has no active payment method for this invoice. Connect Stripe or add bank details in the business's payment settings. If Stripe was connected before, our nightly check may have found the connection broken; you see a warning and can reconnect. See Stripe.
I cannot refund through the app (rail_capability_missing)
The payment method has no refunds through us, for example bank transfer. Send the money back yourself, then record the refund manually. See Refunds.
Stripe or another provider returns an error (upstream_error)
The provider did not answer as expected. Wait a moment and retry. If it keeps happening, check the provider's own status page and contact support with the request id.
Links your clients open
| Code | Cause | Fix |
|---|---|---|
token_invalid | The link is wrong or incomplete. | Ask the business to send the link again. Check that it was not cut off in the email. |
token_expired | The link has expired. | Send the document again or create a new share link. |
token_revoked | The link was cancelled, for example because the invoice was voided. | If the invoice is still valid, create a new share link. |
Team and roles
| Code | Cause | Fix |
|---|---|---|
permission_denied | Your role does not include the permission this action needs. | Ask the Owner or someone with team.manage to change your role. |
business_out_of_scope | You cannot reach this business. | Ask for the business to be added to your business scope. |
feature_locked | A Team feature on the Free plan, such as role editing, the audit log screen or the AI agent without credits. | Upgrade to Team, or for the agent buy a pack or connect your own key. |
plan_limit_reached | Your plan has no more seats, or you reached a fair-use limit. | Upgrade to Team or add a seat. See Fair-use limits. |
permission_not_grantable | A role change would give a permission you do not hold, or an Owner-only permission. | Only grant keys you hold yourself. Account deletion and ownership transfer stay with the Owner. |
role_locked | The Owner role cannot be edited, reset or deleted. | No action needed; the Owner always has every permission. |
role_in_use | You tried to delete a role that members still use. | Move those members to another role first. |
last_owner | The change would leave the account without an Owner. | Make sure another Owner exists first. |
AI credits and billing
| Code | Cause | Fix |
|---|---|---|
ai_credits_exhausted | No AI credits left. | Buy a credit pack, upgrade to Team (on Free) or connect your own AI key. |
billing_card_required | The Free welcome credits need a verified card. | Add a card in Settings > Usage. It is verified for $0 and never charged. |
card_not_eligible | Prepaid cards cannot unlock the welcome credits. | Use a debit or credit card, or buy a credit pack (prepaid cards work there). |
welcome_credits_not_eligible | This card or account already had welcome credits, or the first month has passed. | Buy a credit pack or connect your own AI key. |
money_back_not_eligible | Not the first Team payment, more than 30 days ago, or the guarantee was used. | You can still cancel Team in the Stripe Customer Portal. |
I see a red Payment failed banner
Your Team renewal failed. Everything keeps working for 5 days. Update your card in the Stripe Customer Portal from Settings > Billing and the banner goes away once Stripe confirms the payment. See Failed renewal and downgrade.
I bought a credit pack but the credits are not there yet
Credits are added when Stripe confirms the payment to us, which usually takes moments. Refresh Settings > Usage. If they do not appear, contact support with the time of purchase.
The API
| Code | HTTP | Cause | Fix |
|---|---|---|---|
unauthenticated | 401 | Missing, wrong or revoked API key or token. | Send Authorization: Bearer <key>. Create a new key if it was revoked. |
scope_missing | 403 | The key or token lacks the scope for this action. | Create a key with the scope you need. |
validation_failed | 422 | The input is not valid. | Read details.issues for each field and its problem. |
invalid_json | 400 | The body is not valid JSON. | Check quotes and commas. |
not_found | 404 | The resource does not exist or you cannot see it. | Check the id and that the key belongs to the right account. |
idempotency_key_reused | 409 | The same Idempotency-Key was sent with a different body. | Use a new key for a new request. |
idempotency_in_progress | 409 | A request with the same key is still running. | Wait and retry with the same key. |
confirmation_required | 428 | A destructive action or send needs "confirm": true. | Check the preview, then retry with "confirm": true. |
rate_limited | 429 | Too many requests. | Wait for Retry-After seconds. |
not_configured | 503 | A service on our side is not set up yet. | Try again later. |
maintenance | 503 | The service is in maintenance. | Check the status page and retry later. |
internal_error | 500 | Something went wrong on our side. | Retry. If it persists, contact support with the request_id. |
Send money as a string of integer minor units, such as "120000" for 1,200.00. Floating-point amounts such as 1200.00 are rejected with validation_failed. See Money and currencies.
Is it us?
If several things fail at once, check status.freeinvoiceautomation.com for outages before you dig further.