Replicate API Monitoring Guide 2026

Covers: Prediction API, hardware availability, and webhook delivery

Covers: Your API token usage, spend, and billing

Malformed request — invalid model version, missing required input field, or bad parameter type

Check the response body against the specific model's input schema. Each model on Replicate defines its own input parameters, so validate against that model's current schema, not a generic one.

Missing or invalid API token

Verify your REPLICATE_API_TOKEN is set and current. Generate a fresh token from your Replicate account settings if needed.

Billing issue — payment method failed or spend limit reached

Check your billing settings and spend limit configuration in the Replicate dashboard. This is a billing state, not a transient error.

Model or specific model version not found

Verify the model owner/name and version hash are correct and current. Model authors can push new versions, and old version hashes may be removed.

Input validation failed against the model's schema

Check required vs. optional fields and valid value ranges for the specific model you are calling — schemas vary significantly between models.

Rate limit or concurrent prediction limit exceeded

Implement exponential backoff and cap concurrent in-flight predictions to your account tier limit. Consider queuing requests client-side rather than firing them all at once.

The model run itself errored — not an HTTP-level failure

Read the prediction's error field for the model-specific failure reason. Common causes: invalid input for that model, out-of-memory on the hardware, or a bug in the model code.

Server-side error or temporary overload on Replicate infrastructure

Retry with backoff. Persistent 500/503s across multiple requests and multiple models indicate a genuine platform incident — check status.replicate.com.

Monitor the API layer itself (prediction creation, not full model execution) from outside your infrastructure on a schedule.

• →Monitor prediction creation on a lightweight, fast model
• →Alert on: non-200 responses when creating predictions, SSL issues
• →A synthetic monitor with email/Slack/webhook alerts catches this before users report it

Track these metrics in your observability stack (Better Stack Logs, Datadog, Grafana):

• • Prediction status: failed rate — per model, since failure rates vary widely by model
• • Cold-start frequency and duration — track separately from actual model processing time
• • Webhook delivery success rate — a stuck "processing" prediction may mean a missed webhook, not a hung job
• • 429 rate — signals you're exceeding your concurrency limit for a given model
• • Spend velocity — hardware-second billing can spike unexpectedly with heavier models

Since predictions run async, set a timeout that reconciles state if a webhook never arrives:

// Fallback reconciliation if a webhook doesn't arrive in time
async function reconcileStuckPredictions() {
  const pending = await db.predictions.findMany({
    where: { status: 'processing', createdAt: { lt: fifteenMinutesAgo() } },
  });

  for (const p of pending) {
    const current = await replicate.predictions.get(p.id);
    if (current.status !== 'processing') {
      await db.predictions.update(p.id, { status: current.status });
    } else {
      alerting.notify(`Replicate prediction ${p.id} stuck > 15min`);
    }
  }
}

How do I check if the Replicate API is down?

Check the official status page at status.replicate.com for real-time incident updates on prediction creation, hardware availability, and webhook delivery. API Status Check also maintains a dedicated Replicate status guide with troubleshooting steps and monitoring recommendations.

What are the Replicate API rate limits?

Replicate limits are primarily driven by account tier and available hardware capacity for the model you are running, rather than a single flat requests-per-minute number. Free and low-tier accounts have lower concurrency for predictions; paid accounts unlock higher concurrent prediction limits. Check your exact quota in the Replicate dashboard.

Why does my Replicate prediction take much longer than expected?

Replicate runs models on-demand hardware, and a "cold start" — spinning up a new instance when no warm instance is available — can add tens of seconds to a minute before a prediction even begins processing. This is normal behavior, not an error. Track cold-start frequency separately from actual processing time to avoid false-positive latency alerts.

Should I poll for prediction status or use webhooks?

Webhooks are strongly preferred for production. Polling the prediction status endpoint on a tight interval adds load and latency, and can itself contribute to rate limiting. Configure a webhook URL on prediction creation and let Replicate notify you when the prediction succeeds, fails, or is canceled.

What does a Replicate prediction status of "failed" mean?

A "failed" status means the model run itself errored — often due to invalid input for that specific model, an out-of-memory condition on the hardware, or a bug in the model's code. Check the prediction's error field for the specific message; this is distinct from an HTTP-level API error when creating the prediction.