FAQ / Troubleshooting

JWT tokens in OrcaPulse expire after seven days. When a token expires, the platform returns a 401 Unauthorized response. Log in again to receive a new token. There is no automatic token refresh Automation re-authentication is required after expiration.

This error means the Authorization header is missing or does not contain a valid Bearer token. Make sure your request includes the header in the format Authorization: Bearer <token>. If using the frontend, clearing local storage and logging in again usually resolves this.

Each OAuth provider stores a provider-specific ID (googleId, microsoftId, etc.) on the user record. If you originally registered with email/password and later try to sign in with an OAuth provider, the system may create a separate account if the email does not match. Contact support if you need accounts merged.

Use the password reset flow, which sends a six-digit OTP to your registered email address. The OTP is valid for ten minutes and allows up to five verification attempts. You must wait at least one minute between OTP requests.

OTP requests are rate-limited to prevent abuse. You must wait at least one minute between verification code requests. This applies to signup verification, password resets, and account deletion confirmation codes.

OTP codes are valid for ten minutes after generation. If your code has expired, request a new one. Make sure to enter the code promptly after receiving it. Expired codes are automatically cleaned up every five minutes.

After five incorrect verification attempts, the OTP is invalidated for security. Request a new verification code and try again. The response will show how many attempts remain before lockout.

Account deletion is a two-step process. First, request a deletion code via the account settings, which sends an OTP to your email. Then confirm the deletion with the code. This permanently removes your account, all leads, workflows, assistants, calls, and transactions. This action cannot be undone.

This means your credit balance is below the required amount for the operation. The checkCredits middleware blocks the request before execution. Purchase more credits through the billing page, or enable auto-recharge to prevent this in the future. The error response includes your current available balance.

Auto-recharge requires three things: a saved payment method, the feature enabled in settings, and a configured threshold and recharge amount. The minimum threshold is five credits and the minimum recharge amount is twenty dollars. Check that your saved card has not expired. Failed recharge attempts trigger an email notification.

Credit addition depends on the Stripe webhook confirming the payment via the checkout.session.completed event. If the webhook is delayed or fails, credits may not appear immediately. Check your transaction history for a pending status. The system also prevents duplicate credit additions if the webhook fires twice.

OrcaPulse deducts credits after successful completion to ensure you are never charged for a failed operation. The pre-operation check only verifies that you have enough credits. The actual deduction happens when the call, message, or generation completes successfully.

If your card is declined, you will see a "Card declined" error. Update your payment method in the billing settings and try again. Make sure the card has sufficient funds and has not expired. You can also try a different card by adding a new payment method.

Phone numbers have a monthly recurring cost that is billed automatically. A daily cron job (running at 02:15 UTC) checks each user's phone number billing date and deducts the monthly rental cost from their credit balance when due. The default rate is $1.15 per month if exact pricing cannot be fetched from Twilio.

The system automatically sends alerts when your credit balance drops below a configurable threshold. To prevent workflow interruptions, enable auto-recharge with a saved payment method so credits are replenished automatically when your balance gets low.

Check the workflow status Automation only workflows with an Active status execute. If the workflow is in Draft, Paused, or Archived status, it will not process any leads. Also verify that the workflow has at least one properly configured step and that the scheduling settings (timezone, day/night mode) allow execution at the current time.

The admin execution monitor shows currently executing leads and upcoming pending leads. If leads appear stuck, check the system health endpoint for database connectivity and response time issues. Wait steps in workflows also cause leads to appear paused until the configured delay completes. Leads stuck for more than 15 minutes may be automatically marked as failed due to execution timeout.

The workflow test endpoint runs a simulation against sample data. If it returns no results, verify that the workflow has valid step configurations and that any referenced templates (email, SMS) exist and are active.

Check whether leads are being imported from multiple sources simultaneously. The platform checks for duplicates during import, but if the same contact is submitted through different channels or import batches, duplicates may be created. Review your import sources and CRM sync settings.

OrcaPulse detects the timezone from the lead's phone number when available and falls back to UTC if no timezone is detected. If you have day/night mode enabled, calls outside business hours are automatically bumped to the next available window (e.g., a call scheduled at 10 PM with business hours 9 AM–9 PM will be rescheduled to 9 AM the next day).

If a lead has been in executing status for more than 15 minutes (configurable via LEAD_EXECUTION_TIMEOUT_MINUTES) without any state update, the system marks it as failed with a "execution-timeout" reason. The system also checks the call status to determine if the call actually completed or genuinely timed out.

The system expects data rows below the header row. If your file only contains a header row with no lead data, you will see this error. Make sure your spreadsheet has at least one row of lead data with a name and either an email or phone number.

Rows are skipped if they are missing a name (column 1) or missing both an email (column 2) and phone number (column 3). The import response includes a skippedRows array showing which rows were skipped and why. The system reads columns by position, not by header names.

Phone numbers from Excel files are automatically converted to strings. If a number does not start with a + prefix, the system adds one automatically. Make sure your phone numbers include the country code (e.g., +1 for US, +44 for UK) for best results.

This error means every row in your file failed validation. Each row must have a name in the first column and either an email in the second column or a phone number in the third column. Check that your data is in the correct column positions.

AI call steps require the lead to have a valid phone number. If a lead was imported with only an email address, the call step will fail. Make sure leads have phone numbers before assigning them to workflows that include AI call steps.

Assistants must pass a preflight canary test before activation. If the test fails, the assistant is forced to inactive status and you will see "Assistant canary failed. Cannot activate assistant." Check the preflightErrors array in the response for specific issues Automation common causes include invalid voice selection, unsupported model, or missing API keys.

The assistant controller validates voices and models against a supported list. If you use an invalid voice, you will see "Invalid voice" with the list of supported values. Similarly, invalid models return "Invalid model" with supported options for the selected provider. Check the error response for the exact valid options.

Assistants that are currently linked to one or more workflows cannot be deleted. You will see "Cannot delete. N workflow(s) are using this assistant." Remove the assistant from all workflows first, then delete it.

If call transfer is enabled on your assistant, a valid transfer number is required. You will see "Transfer number is required when call transfer is enabled" if the number is missing. Make sure the transfer number is a valid phone number that can receive calls.

Call outcomes include completed, failed, no-answer, busy, and voicemail. Failed calls can be retried Automation only failed, no-answer, or busy calls are eligible for retry. Completed calls cannot be retried. Check the call's endReason field for detailed failure information.

WhatsApp message templates must be approved by WhatsApp before they can be used in live sends. The approval process is handled by WhatsApp through the Twilio Content API and can take up to 24 hours. Templates categorized as Marketing typically take longer than Utility templates. You cannot send with unapproved templates Automation the system will return "Template not approved" or "Only approved templates can be activated."

Each WhatsApp number can only be connected once to your account. If you see a 409 conflict error, the number is already linked. Check your WhatsApp accounts list. If the connection appears broken, try disconnecting and reconnecting the number.

WhatsApp templates require a valid Twilio Content SID to send messages. If your template is missing this, it may not have been properly synced with Twilio. Re-create the template or check that your Twilio Content API integration is configured correctly.

Bulk WhatsApp sends are limited to a maximum of 1,000 recipients per request. If you need to reach more contacts, split them into batches of 1,000 or fewer.

Verify that your CRM integration credentials are valid and that the integration is marked as active. The CRM sync step in workflows requires a properly configured integration with encrypted API keys. Check the webhook events log for any sync failure details.

Webhook failures are typically caused by the receiving endpoint being unreachable, returning a non-2xx status code, or timing out. Check that your webhook URL is accessible from the public internet and responds within the timeout window.

Instagram integration requires active OAuth connections with the correct permission scopes: instagram_basic, instagram_manage_messages, and instagram_manage_comments. If tokens have expired or permissions were revoked, messages will not flow. Re-authenticate from integrations settings. Also make sure your Facebook Page is linked to an Instagram Business account.

If the OAuth callback fails, you will be redirected with an error parameter (e.g., ?error=auth_failed or ?error=no_pages_found). Common causes include expired app permissions, revoked access, or the Facebook/Instagram page not being found. Try re-initiating the OAuth flow from a fresh browser session.

Each account can only have one rented phone number at a time. If you need a different number, release your current number first and then purchase a new one. You will see "You already have a rented phone number. Release it first." if you try to rent a second.

Phone number availability depends on the Twilio inventory for your selected country and area code. If no numbers are found, try a different area code or country. Search failures may also occur if Twilio credentials are not configured on the platform Automation contact support if this persists.

When saving your own Twilio credentials, the system validates them by making a test API call. If you see "Invalid Twilio credentials. Please check and try again", double-check your Account SID and Auth Token in your Twilio dashboard. Make sure the credentials have the necessary permissions for phone number management.

This error means your account does not currently have an active rented phone number. Check your phone number settings to confirm whether a number is currently active on your account.

Check that your email provider is properly configured with valid API credentials. The system validates provider credentials when testing Automation if authentication fails, you will see "Invalid API key - authentication failed." For Mailgun, make sure your domain is included. For AWS SES, make sure your secret key is provided.

If the email provider OAuth callback fails, you will be redirected with an error parameter like ?email_error=gmail or ?email_error=outlook. Try re-initiating the connection from a fresh browser session. Make sure you grant all requested permissions during the OAuth flow.

Template variables use the {{variableName}} syntax (e.g., {{name}}, {{email}}, {{company}}). Make sure the variable names in your template match the field names in your lead data exactly. The system auto-extracts variables from templates Automation check the extracted variables list to verify detection.

If you can no longer generate TOTP codes, you will need to contact support to have 2FA disabled on your account. The platform does not currently provide backup recovery codes. An admin can assist with account recovery.

TOTP codes are time-sensitive. The system allows a one-window tolerance to account for clock skew between your device and the server. Make sure your device's clock is set to automatic time. If codes are still failing, disable and re-enable 2FA to generate a new secret.

The temporary 2FA secret expires after ten minutes. If you did not scan the QR code and verify within that window, start the setup process again to generate a new QR code and temporary secret.

Navigate to the Support section in the OrcaPulse portal. Select a category (Technical Issue, Billing Question, Feature Request, Account Help, Integration Problem, General Inquiry, or Other), set a priority (Low, Medium, or High), and describe your issue.

Each user can have one open ticket at a time. Close or resolve your current ticket before opening a new one. You will see an error if you try to create a second open ticket.

Yes. Both users and support staff can add comments to open tickets through the threaded comment system. Comments cannot be added to tickets that have already been closed.