Skip to content
Recuro Docs

Troubleshooting & FAQ

Common errors

Timeout

Error: Execution failed with reason timeout

Cause: Your endpoint did not respond within the configured timeout (default: 30 seconds).

Fix:

  • Check your endpoint for slow database queries, external API calls, or heavy processing
  • Increase timeout_seconds (up to 300) on the cron or queue if the endpoint legitimately needs more time
  • Consider returning 202 Accepted immediately and processing asynchronously

DNS error

Error: Execution failed with reason dns_error

Cause: Recuro could not resolve the hostname in your URL.

Fix:

  • Verify the domain name is spelled correctly
  • Ensure DNS records are configured (check with dig or nslookup)
  • If using a private/internal hostname, it must be resolvable from the public internet — Recuro cannot reach private networks

SSL error

Error: Execution failed with reason ssl_error

Cause: TLS handshake failed when connecting to your endpoint.

Fix:

  • Check that your SSL certificate is valid and not expired
  • Ensure the full certificate chain is installed (intermediate certificates included)
  • Verify the domain in the certificate matches the URL hostname
  • Check for TLS version compatibility (Recuro supports modern TLS versions)

Connection error

Error: Execution failed with reason connection_error

Cause: Could not establish a TCP connection to your server.

Fix:

  • Verify your server is running and accepting connections on the expected port
  • Check firewall rules — ensure inbound traffic is allowed from the public internet
  • Verify the port is correct (443 for HTTPS, 80 for HTTP)
  • Check if your hosting provider’s load balancer or WAF is blocking requests

HTTP client error (4xx)

Error: Execution failed with reason http_client_error

Cause: Your endpoint returned a 4xx status code (400, 401, 403, 404, etc.).

Fix:

  • 401/403: Check authentication headers. If your endpoint requires a token, include it in the cron/job headers
  • 404: Verify the URL path is correct
  • 400: Check the request body format — ensure your payload matches what the endpoint expects
  • 429: Your endpoint is rate-limiting Recuro. Reduce the cron frequency or add parallelism limits to the queue

HTTP server error (5xx)

Error: Execution failed with reason http_server_error

Cause: Your endpoint returned a 5xx status code.

Fix:

  • Check your server’s application logs for errors
  • Verify your database and external dependencies are healthy
  • If intermittent, this may resolve on retry (for queue jobs with retries enabled)

Assertion failed

Error: Execution failed with reason assertion_failed

Cause: The HTTP response did not satisfy one or more success assertions.

Fix:

  • Check the execution details in the dashboard to see the actual response
  • Compare the response against your assertion rules
  • Common issue: endpoint returns 200 but the response body changed format
  • Update your assertions if the expected response has legitimately changed

Limit exceeded

Error: Execution failed with reason limit_exceeded

Cause: Your team has reached its monthly request hard limit.

Fix:

  • Check your usage on the Usage page
  • Reduce the number of active crons or their frequency
  • Upgrade your plan for a higher limit

Diagnostic checklists

My cron is not firing

  1. Is the cron active? Check the cron detail page — is_active must be true
  2. What is next_run_at? If it is in the future, the cron has not reached its scheduled time yet
  3. Has it fired recently? Check last_run_at — if it is recent, the cron is firing but may be failing
  4. Check executions: Go to Crons > [cron] > Executions and look for recent entries
  5. Check the cron expression: Verify the expression matches your intended schedule. Use the Cron Expression Generator to validate
  6. Check usage limits: If you are at your hard limit, cron executions are blocked

My job keeps failing

  1. Check the run details: Go to Jobs > [job] and inspect the run — look at the failure reason, error message, and response body
  2. Is the endpoint reachable? Try calling the URL directly with curl to verify it responds
  3. Check the failure reason:
    • timeout → Endpoint too slow, increase timeout or optimize the endpoint
    • connection_error → Server unreachable, check firewall and server status
    • dns_error → Bad hostname, verify the URL
    • ssl_error → Certificate issue, check SSL config
    • http_client_error → Wrong URL, missing auth, or bad payload
    • http_server_error → Server-side bug, check application logs
    • assertion_failed → Response changed, update assertions
  4. Are retries exhausted? Check attempt_number and final_status. If dead_lettered, the job failed all retries
  5. Is the queue active? An inactive queue causes all dispatched jobs to fail

I am not receiving alerts

  1. Is alerting configured on the resource?
    • Crons: Check that alert_threshold is set (1, 2, or 3)
    • Queues: Check that alerts_enabled is true
  2. Check your notification channel: Go to Settings > Notifications and verify the channel and webhook URL
  3. Test the webhook: Click Test on the notification settings page
  4. Check for maintenance windows: Active maintenance windows suppress alerts for the affected resources
  5. Check the Alerts page: Alerts may be created but not delivered if the notification channel is misconfigured — look for alerts in the dashboard
  6. Check spam folders: For email alerts, check your spam/junk folder

Frequently asked questions

What HTTP methods does Recuro support?

GET, POST, PUT, PATCH, and DELETE. The default is POST.

Can I schedule jobs for a specific date and time?

Use the delay parameter to schedule a job for the future. The delay is in seconds from now (up to 86,400 seconds / 24 hours).

For crons, the cron expression controls the recurring schedule. There is no one-time scheduled execution for crons — use a queue job with a delay instead.

What happens if my endpoint is down when a cron fires?

The execution is marked as failed with the appropriate failure reason (connection_error, timeout, etc.). If alert_threshold is configured, the alert system tracks consecutive failures and notifies you.

Cron executions are not retried — each scheduled firing is independent. The cron fires again at the next scheduled time.

What happens if a job fails and retries are disabled?

The job is marked failed with final_status: failed_no_retries. It does not enter the dead-letter queue. If you have a callback_url configured, the callback fires with the failure details.

Can I use private/internal URLs?

No. Recuro runs in the cloud and can only reach endpoints accessible from the public internet. Internal hostnames (e.g., http://localhost, http://192.168.x.x) are blocked for security.

How do I rotate my API token?

Go to Settings > API and click Regenerate. The old token is immediately invalidated. Update all integrations before regenerating.

Is there a rate limit on the API?

The POST /api/crons and POST /api/jobs endpoints do not have a separate rate limit, but your team’s monthly request quota applies to all executions. The waitlist endpoint has a rate limit of 10 requests per minute.

How long are execution logs retained?

Cron executions and job runs are retained as long as the resource exists. Dead-lettered jobs are automatically cleaned up after the queue’s dlq_retention_days (default: 14 days).

Can I use the same API token for multiple teams?

No. Your API token is scoped to your current team. Switch teams in the dashboard to change the team context for your API calls. If you need tokens for multiple teams, switch to each team and generate a token from that context.

Does Recuro support 6-field cron expressions (with seconds)?

No. Recuro uses standard 5-field cron expressions with minute-level granularity. The minimum interval is every minute (* * * * *).

Next steps