Errors & Rate Limits¶

The Abelo API uses standard HTTP status codes, structured JSON error responses, and token-bucket sliding-window rate limiting.

1. HTTP Status Codes¶

Code	Status	Meaning
`200`	OK	The request completed successfully and the response body contains the requested resource.
`201`	Created	The resource (e.g. customer profile or webhook configuration) was successfully created.
`204`	No Content	The request was successful and there is no response body (e.g. profile or webhook deletion).
`400`	Bad Request	Business rule violation (e.g. campaign inactive, missing template parameter, duplicate phone number).
`401`	Unauthorized	Missing, invalid, or expired API authentication credentials or invalid HMAC signature.
`403`	Forbidden	API key missing required scope, or target recipient missing promotional consent.
`404`	Not Found	The requested resource (e.g. campaign ID, profile ID, or webhook ID) does not exist.
`409`	Conflict	Resource cannot be modified (e.g. attempting to edit/delete profiles originating from connected Shopify/WooCommerce stores).
`422`	Unprocessable Entity	Request body failed JSON schema validation (e.g. malformed phone number, missing required fields).
`429`	Too Many Requests	Rate limit exceeded. Back off according to `Retry-After`.
`500`	Internal Server Error	An unexpected error occurred on the server.

2. Error Response Schemas¶

Standard Validation Error (`422 Unprocessable Entity`)¶

Returned by FastAPI when payload fields violate type, regex, or required schemas:

{
  "detail": [
    {
      "loc": ["body", "recipient", "value"],
      "msg": "Invalid E.164 phone number format",
      "type": "value_error"
    }
  ]
}

Business Logic Error (`400 Bad Request` / `403 Forbidden`)¶

{
  "error": "Promotional consent not found for profile."
}

3. Rate Limiting¶

Rate limiting in Abelo is enforced globally using a Redis Token Bucket (Sliding Window) algorithm scoped per API Key (organization_id + key_id).

Rate Limit Specifications¶

Parameter	Value	Description
Bucket Capacity	100 requests	Maximum burst capacity of tokens available in the bucket.
Window	60 seconds	Time window for complete bucket replenishment.
Refill Rate	~1.67 tokens / sec	Tokens are continuously replenished back into the bucket in real time.
Breach Response	HTTP 429	Returns `429 Too Many Requests` with a `Retry-After` header when empty.

Rate Limit Response Headers¶

Every authenticated API response includes real-time rate limit telemetry headers:

Header	Description	Example
`X-RateLimit-Remaining`	The number of tokens remaining in your bucket for immediate use.	`98`
`X-RateLimit-Reset`	UNIX timestamp when your bucket will be 100% full.	`1771596780`
`Retry-After`	(Included on `429` errors) Seconds to wait before attempting the next request.	`1`

Handling HTTP 429 (Rate Limit Exceeded)¶

When your application consumes all available tokens, the API responds with 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1771596780
Retry-After: 1

{
  "error": "Rate limit exceeded"
}

Retry Best Practice

Read the Retry-After header and implement exponential backoff with jitter in your API client.