Work out what an error means before opening a ticket

Goal

Identify what actually blocked an action, apply the check that belongs to it, and only escalate what genuinely needs another person.

Prerequisites

• You know which record and which action failed, and roughly when.
• You can read the exact error text that was shown, including any code.
• You have Support access if the problem turns out to need escalation.

Steps

1. Write down the exact wording of the error and the code if one is shown. Codes are stable, so they identify the cause far better than a description of the symptom does.
2. Refresh a failed read once. Before repeating a send, payment, import or other write, inspect the record and activity to check whether it already completed. If the outcome is unknown, contact support instead of risking a duplicate.
3. Check whether the issue affects other users or records. A colleague can try opening the same screen on another device; do not ask them to repeat a payment or send. Different results help narrow the cause but do not prove it.
4. Check the three things that block the most actions: whether outbound email is connected and tested, whether the plan still covers the feature or limit involved, and whether your role has the permission the action needs.
5. Match the code you captured against the list under Troubleshooting and run its check.
6. For a plan or permission message, check the owning screen or ask your workspace owner. If the displayed access looks wrong, contact support@4fleet.io.
7. If several unrelated areas fail at once, treat it as a wider problem, stop repeating the action, and report it once with the times you saw it.
8. When the check does not resolve it, open Support, select Report a problem, and include the exact error text, the code, the record reference, the time with its timezone, and what you already tried.

Expected result

Every failure is either resolved by the check that belongs to its code, or escalated once with the code, the record, and the steps already taken attached to it.

Troubleshooting

Sending and email

• EMAIL_NOT_CONFIGURED: no usable mailbox is connected, so nothing left the system. The record itself is saved. Connect a mailbox and run the connection test, or share the document link manually meanwhile.
• EMAIL_SEND_FAILED: inspect the exact error and sending activity. A send can fail for several reasons, and an unknown outcome is not proof that nothing was delivered. Check the recipient and connection result before retrying; contact support@4fleet.io if delivery is uncertain.

Plan, permission and access

• LIMIT_REACHED, FEATURE_UNAVAILABLE, TRIAL_EXPIRED, GRACE_PERIOD, SUBSCRIPTION_REQUIRED, ACCOUNT_LOCKED: the plan or its payment state blocked the action, not a defect. Open Settings > Finance to see which limit or state applies. Data is never removed by any of these.
• AI_LIMIT_REACHED: the AI operations included in the plan are spent for the current billing period. The allowance resets with the period, and quoting, sending and dispatch all work without AI.
• FORBIDDEN: the permission for this action is not on your role. Ask the company owner to review the role rather than working around it.
• UNAUTHORIZED: the request could not be authenticated. Refresh or sign in again if prompted. Inspect the record before repeating a write; one failed request alone does not prove the whole session ended.
• TWO_FACTOR_REQUIRED: the session has not passed the two-factor challenge. Sign in again and complete it. If the code is rejected, check the clock on the authenticator device.

Records and workflow

• VALIDATION_ERROR: a field was rejected. Read the message next to the field, correct it, and submit again. Nothing was saved.
• NOT_FOUND: the record does not exist or does not belong to the company you are signed into. Check the active company before assuming data loss.
• QUOTE_EXPIRED: the validity window passed, so the client link is dead on purpose. Re-issue the quote and send the new link.
• PASSENGER_DETAILS_REQUIRED: the job has no resolved passenger yet. Add the passenger separately from the billing client.
• STRUCTURAL_CHANGE_TARGET_REQUIRED: the enquiry already has a live booking, so the new journey has two possible homes. Choose which booking receives it.
• TENDER_CONFLICT and TENDER_AWARDED_LEG: the leg is already in an open tender or already awarded. Resolve the existing tender or award first.
• AWARD_MARGIN_CONFIRMATION_REQUIRED: the partner payout is at or above the client fare on a leg, or the fare is missing there. Check the fare and payout on each leg before confirming.
• INVITE_LINK_UNAVAILABLE: the client record has no usable email, or an invite is still outstanding. Check both before sending another.
• UNUSUAL_DUE_DATE: the due date is far from the issue date, which is usually a typed year. Confirm it only if the terms really are that long.
• STRIPE_NOT_CONFIGURED: card payments are not connected, so no payment link can be produced. Send the invoice without the link and record payment manually meanwhile.

Faults worth escalating

• INTERNAL_SERVER_ERROR: the server could not complete the response. A write may have completed before the error; inspect its result before retrying. Report persistent or uncertain failures with the time and record reference to support@4fleet.io.
• An error with no code at all: capture a screenshot showing the whole message, note the route you were on and the time, and report it. A message without a code is exactly what the error catalogue needs to grow.