CLI exit codes
| Exit code | Class | What to do |
|---|---|---|
| 0 | Success | Nothing. The command completed. |
| 2 | Usage or validation | Fix the arguments. Run the command with --help. |
| 10 | Authentication | Run blobyard login again, or replace an expired token. |
| 11 | Authorization | Use a principal or scope that is allowed to act here. |
| 12 | Not found | Check the URI, slug, or identifier with blobyard ls. |
| 13 | Conflict | Re-read current state, then retry with fresh input. |
| 14 | Plan limit | Free capacity or upgrade the plan on the Billing page. |
| 20 | Network | Check connectivity and retry. |
| 21 | Provider unavailable | Wait and retry. The storage provider rejected the call. |
| 22 | Transfer | Retry the upload or download. Bytes or checksums did not complete. |
| 23 | Rate limited | Wait for the Retry-After interval before retrying. |
| 70 | Internal | Retry once, then report the request ID. |
| 130 | Interrupted | The command was interrupted before finishing. |
Scripts should branch on the exit code and parse the JSON envelope rather than matching human text.
API error codes
| Error code | HTTP status |
|---|---|
| INVALID_REQUEST | 400 |
| AUTH_REQUIRED, INVALID_TOKEN, TOKEN_EXPIRED | 401 |
| PLAN_LIMIT | 402 |
| FORBIDDEN | 403 |
| NOT_FOUND | 404 |
| CONFLICT, UPLOAD_INCOMPLETE | 409 |
| CHECKSUM_MISMATCH | 422 |
| RATE_LIMITED | 429 |
| INTERNAL_ERROR | 500 |
| STORAGE_ERROR | 502 |
| PROVIDER_UNAVAILABLE | 503 |
Every response carries an X-Request-Id header and matching requestId field. Quote the request ID and the stable code when reporting a problem, never raw tokens or signed URLs.
Common failures
- Authentication failures after a long break usually mean the thirty-day refresh token lapsed. Run blobyard login.
- PLAN_LIMIT failures name the pooled allowance that is full. The Billing page shows current usage.
- CHECKSUM_MISMATCH means bytes changed between hashing and completion. Rerun the transfer.
- Repeated RATE_LIMITED responses on public share or inbox URLs mean the fixed per-minute window is exhausted.