Neptune API rate limit hit mid-metric backfill and agent failed to log the remaining series error

TL;DR

Backfill in logged batches under the rate limit, with the series list as state: record which series are written for which runs, pace calls under the API's limits, and resume with only the unwritten series after a limit or failure. Verify the backfill per run by reading back point counts, because a silent partial series looks identical to a complete one until plotted.

Neptune API rate limit hit mid-metric backfill and agent failed to log the remaining series error

Use this when

• The run or call fails with this symptom: Neptune API rate limit hit mid-metric backfill and the agent failed to log the remaining series.
• You are working on an agent backfilling metric series into Neptune after an outage or migration and the failure repeats on the same run or configuration.
• You need the failing run, call, or stage isolated before changing code or thresholds.

Not for this skill when

• A backfill blocked by a hard quota rather than a rate window, where pacing cannot help and the fix is quota or scope.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Build the backfill manifest: runs and series with expected point counts from the source data. Verify: the manifest defines completeness
2. Write in batches, marking each series done in the manifest only after a read-back confirms its points. Verify: progress is verified, not assumed
3. On a rate limit response, pause for the indicated window and resume from the manifest's remaining series. Verify: limits pause the job without losing position
4. Finish with a manifest-versus-server comparison and report any series still short. Verify: final completeness is proven or gaps are named

Variant phrasings

neptune rate limit mid metric backfill remaining series agent

The verbatim phrasing.

agent backfill neptune series incomplete 429 resume

The resume phrasing.

neptune api throttled backfill manifest read back fix

The manifest phrasing.

Compatibility: Neptune API driven by agents performing metric backfills

Why it happens

A backfill is a long sequence of ordinary calls, so hitting a rate limit somewhere inside it is expected, not exceptional. Without a manifest, the agent cannot distinguish written from unwritten series, and the unwritten tail is discovered weeks later as holes in old runs.

Edge cases / pitfalls

• Point-count read-backs cost calls too; budget them into the pacing plan.
• Series written under a wrong namespace during backfill pollute the run; verify names as well as counts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_foSwWKaYFNy1Qrd6Vwj1kA