API Errors

Introduction

The ReBattery API uses standard HTTP status codes. Error responses include a JSON body with details. Some errors are retryable; others indicate a problem with the request.

Error Format

All error responses follow this shape:

json

{
  "error": "Short error description"
}

Validation errors (422) also include field_errors:

json

{
  "error": "Validation failed",
  "field_errors": [
    "manufacturer is required"
  ]
}

Status Code Reference

Status	Error	When it happens	What to do
400	Invalid JSON body	Malformed JSON in the request body	Fix the JSON syntax and retry
401	Invalid or missing API key	No `Authorization` header, wrong scheme, or invalid/revoked key	Check your API key and ensure the `Authorization: Bearer <token>` header is present
403	API key lacks required scope	The key does not have `listings:write` scope	Create a new API key with the correct scope in Settings
409	Idempotency-Key reuse with different body	Same `Idempotency-Key` header sent with a different request body	Use a fresh idempotency key or send the exact same body
413	Request body too large	Body exceeds 40 MB	Reduce request size, especially base64 image payloads
422	Validation failed	One or more fields are invalid or missing	Review `field_errors` and correct the request
425	Request with this Idempotency-Key is still processing	A previous request with the same idempotency key is still in flight	Wait briefly and retry with the same key
429	Rate limit exceeded	More than 100 requests in 60 seconds for this key	Wait for the `Retry-After` interval and retry with exponential backoff
500	Internal server error	Unexpected server error	Retry with exponential backoff. Contact support if persistent.
500	Failed to create listing	The listing could not be created after validation	Retry with exponential backoff. Contact support if persistent.

Retry Guidance

Retryable: 429, 500, 425 (wait then retry with same key)
Not retryable without changes: 400, 401, 403, 409, 413, 422
Recommended: exponential backoff starting at 1 second, up to 5 retries

[!TIP] Always respect the Retry-After header on 429 responses rather than guessing a delay. If the header is absent, fall back to exponential backoff.

Rate Limit Headers

On 429 responses, these headers are included:

Retry-After: seconds until the limit resets
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: Unix timestamp of reset

Idempotency Conflicts

A 409 response means you reused an idempotency key with a different request body. A 425 response means the original request with that key is still processing. Both behaviours protect against duplicate listings.

[!NOTE] Use UUIDs or composite keys (e.g., <your-internal-id>-<timestamp>) to avoid collisions.

Guides

Documentation