Errors and retries

Every error has the same shape, and the codes are stable, so your code can branch on error.code.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This key or connection can't search these drives: drv_4h7k2m9q8r1t5v6w3x0y.",
    "drive_ids": ["drv_4h7k2m9q8r1t5v6w3x0y"]
  }
}

All codesCopy Anchor Link

How to retryCopy Anchor Link

Retry only 5xx errors and failed connections. A 4xx error keeps returning the same result until you change the request.

Back off between tries: wait one second, then double the wait each time (1, 2, 4, 8 seconds), and stop after four or five tries.

Keep the same effort when you retry. ByteRover never lowers the effort after an error, and your code must not do so without your user knowing, since a medium result in place of a high one is a different product.

Send an idempotency key with calls that change content. That way a retry made after the first call has ended doesn't repeat the work.

IdempotencyCopy Anchor Link

On any call other than a GET, you can send an Idempotency-Key header with a value of your choosing, such as a UUID. If you send the same request with the same key within 24 hours, ByteRover returns the first response instead of doing the work again.

That only applies once the first call has finished successfully. If you send the retry while the first call is still open, both can run.

curl -X PUT https://byterover.ai/api/v1/drives/drv_4h7k2m9q8r1t5v6w3x0y/documents/by-path \
  -H "Authorization: Bearer $BYTEROVER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4c3a-9e2f-8d5b1a7c0e34" \
  -d '{ "path": "/notes/standup.md", "text": "Decisions of 10 November." }'

A key is 1 to 255 characters long. Reusing a key with a different request to the same operation returns IDEMPOTENCY_MISMATCH. Only successful responses are kept, so after an error the same key runs the request again.

VersionsCopy Anchor Link

Drives and documents carry a version number that changes whenever they do. To avoid overwriting another caller's change, send the version you read as expected_version when you change a document's tags, move it or delete it. If the document has changed in the meantime, you get VERSION_MISMATCH.

Operations that fail laterCopy Anchor Link

An upload returns immediately and the work continues in an operation, which can fail even though your call succeeded. Always check the final status:

{
  "id": "op_3g6j9m2p5s8v1y4b7e0h",
  "kind": "ingest",
  "status": "failed",
  "error": { "code": "SUPERSEDED", "message": "A newer revision of the document replaced this one." },
  "retry_after_ms": null
}

Here, a newer upload to the same path replaced the revision, so there's nothing to fix. Follow the newer upload's operation instead.

When ByteRover can't read a file, the operation fails, the document's status becomes failed, and its error field gives the reason. Fix the file and upload it again to the same path. A PDF that's only images fails with the code IMAGE_ONLY_PDF_UNSUPPORTED, on the operation and in the document's error_code field: ByteRover can't read it yet (see Scanned PDFs). For other failures error_code is null.

Get helpCopy Anchor Link

Send support the search_id of a search or the id of an operation, and they can find the call from that. You don't need to send your question or your files.