Errors

BlobRouter v0.1 · Last updated: August 2026 · Architecture version: 2.0

Response shape

All errors return JSON:

{
  "error": "Human readable message",
  "code": "error_code"
}

Optional details may appear for validation context. Stack traces are never returned. Every response includes X-Request-ID — send that to support.

Catalog

Auth

Code	Status
`unauthorized`	401
`forbidden`	403
`plan_limit`	402

Upload

Code	Status
`file_too_large`	400
`invalid_size`	400
`invalid_content_type`	400
`invalid_filename`	400
`file_not_on_provider`	400
`no_providers_configured`	400

Routing

Code	Status
`routing_failed`	400
`provider_unavailable`	503

Files

Code	Status
`file_not_found`	404
`file_already_deleted`	404

Scanner

Code	Status
`connection_failed`	400
`scan_not_found`	404
`scan_already_running`	409
`invalid_role_arn`	400
`credentials_missing`	400
`scanner_credentials_missing`	500

Billing / system

Code	Status
`payment_required`	402
`billing_disabled`	503
`encryption_error`	500
`provider_error`	502
`internal_error`	500
`rate_limit_exceeded`	429

SDK

TypeScript and Python raise BlobRouterError with code and statusCode / status_code.

Authentication Rate limits

⌘I

Getting Started

Guides

Examples

SDK Reference

API

Concepts

Billing

Product

Response shape

Catalog

Auth

Upload

Routing

Files

Scanner

Billing / system

SDK

​Response shape

​Catalog

​Auth

​Upload

​Routing

​Files

​Scanner

​Billing / system

​SDK

Response shape

Catalog

Auth

Upload

Routing

Files

Scanner

Billing / system

SDK