Available nowIn progressLast updated: June 2026

Errors

Lariba Cloud APIs should return predictable errors so clients can distinguish authentication failures, validation problems, rate limits, duplicates, and temporary infrastructure failures.

401 / 403

Auth or policy failure.

422

Event validation failed.

429

Rate limited.

503

Temporary dependency failure.

Standard error body

Error responses should expose a stable code, a readable message, a request id, and whether the client can retry safely.

{
  "error": {
    "code": "invalid_source_key",
    "message": "Source API key is invalid or revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Error reference

Clients should handle 401, 403, 422, 429, and 503 explicitly.

HTTP	Code	Meaning	Retryable
400	bad_request	Malformed JSON, missing required header, or invalid query parameter.	No
401	invalid_source_key	The source API key is missing, invalid, expired, malformed, or revoked.	No
403	source_disabled	The source exists but is disabled and cannot ingest events.	No
403	project_forbidden	The caller is outside the allowed project or workspace boundary.	No
404	not_found	The requested source, event, project, or destination was not found in the caller boundary.	No
409	duplicate_event	The request conflicts with an existing event or duplicate idempotency record.	Usually no
409	conflict	The requested operation conflicts with the current resource state.	Usually no
422	schema_validation_failed	The event envelope or payload failed validation.	No
429	rate_limit_exceeded	The source or project exceeded a quota or rate limit.	Yes
500	internal_error	Unexpected server failure.	Unknown
503	queue_unavailable	The queue or async processing dependency is temporarily unavailable.	Yes
503	storage_unavailable	Durable storage is temporarily unavailable. The event should not be treated as stored.	Yes

Handle authentication errors explicitly

Treat 401 and 403 as configuration or permission problems. Do not retry blindly.

Fix validation errors at the producer

Treat 422 as a payload or envelope issue. Correct the event shape before retrying.

Back off on rate limits

Treat 429 as a throttling signal. Retry later with backoff and jitter.

Retry temporary failures safely

For 503 responses, retry with the same Idempotency-Key so duplicate records are not created.

For temporary failures, retry with the same Idempotency-Key. This keeps retries safe and helps avoid duplicate operational records.

Do not treat a 500 or 503 as confirmation that an event was stored. Preserve event_id and Idempotency-Key, then retry safely when the client can do so.

Authentication and authorization failures should trigger key, source, or project configuration review. They should not be retried in a tight loop.

Error codes should stay stable across API responses, SDK exceptions, dashboard banners, and operational logs.