Error reference

Reference every error the Samva API can return, its HTTP status, cause, response fields, and how to resolve it.

Every Samva API error is returned as a flat JSON body. A _tag field carries the machine-readable discriminator, and the remaining fields are specific to that error type. There is no wrapper object; the fields sit at the top level of the response. The _tag value determines the HTTP status code. For the request and response conventions around errors, see the REST API reference.

{
  "_tag": "ValidationError",
  "message": "Invalid request body",
  "fields": {
    "to": ["Must be a valid email address"]
  }
}

Error types

`_tag`	Status	Cause	How to resolve
`ValidationError`	`422`	The request body or parameters failed validation.	Read `fields` for per-field detail and correct the request.
`UnauthorizedError`	`401`	The API key is missing or invalid.	Check the `X-API-Key` header carries a valid, unrevoked key.
`ForbiddenError`	`403`	The key is valid but lacks permission for the resource.	Use a key whose permissions include the required scope.
`PaymentRequiredError`	`402`	A plan usage limit or entitlement blocks the request.	Reduce usage or upgrade the plan; `currentUsage` and `limit` show the ceiling.
`ResourceNotFoundError`	`404`	The referenced resource does not exist.	Check the id; `resource` and `id` name what was not found.
`ConflictError`	`409`	The request conflicts with existing state (e.g. duplicate).	Reconcile with the existing resource named by `resource`.
`RateLimitedError`	`429`	The organization exceeded its request rate limit.	Back off for `retryAfterSeconds`, then retry.
`FlagDisabledError`	`403`	A feature required by the request is not enabled.	The feature is unavailable for the organization; no client-side fix.
`WebhookEnqueueError`	`500`	The message was accepted but its webhook could not be queued.	Transient; the message send itself succeeded. Retry-safe on the client.
`ExternalServiceError`	`502`	An upstream provider returned an error.	Transient upstream fault; retry with backoff. `provider` names the source.
`BillingProviderError`	`502`	The billing provider returned an error.	Transient; retry with backoff.
`InternalError`	`500`	An unexpected server error.	Retry with backoff; if it persists, contact support.

Response fields

Each error carries only the fields listed for its type. Common fields:

message is present on ValidationError, UnauthorizedError, ForbiddenError, ConflictError, ExternalServiceError, BillingProviderError, and InternalError.
resource and id are present on ResourceNotFoundError.
fields is an optional map of field name to error messages on ValidationError.
retryAfterSeconds is present on RateLimitedError.
currentUsage and limit are present on PaymentRequiredError.
provider is present on ExternalServiceError and BillingProviderError.
flag is present on FlagDisabledError.
reason is present on WebhookEnqueueError.

`ValidationError` (422)

Returned when the request body or parameters fail schema validation. The optional fields map lists per-field error messages.

{
  "_tag": "ValidationError",
  "message": "Invalid request body",
  "fields": {
    "to": ["Must be a valid email address"]
  }
}

`UnauthorizedError` (401)

Returned when the API key cannot be validated. See API keys.

{
  "_tag": "UnauthorizedError",
  "message": "Invalid API key"
}

`ForbiddenError` (403)

Returned when the key is valid but not authorized for the request.

{
  "_tag": "ForbiddenError",
  "message": "API key lacks the required permission"
}

`PaymentRequiredError` (402)

Returned when a plan usage limit or entitlement blocks the request. currentUsage and limit describe the ceiling reached for resource.

{
  "_tag": "PaymentRequiredError",
  "resource": "messages",
  "currentUsage": 10000,
  "limit": 10000
}

`ResourceNotFoundError` (404)

Returned when the referenced resource does not exist. resource and id identify what was not found.

{
  "_tag": "ResourceNotFoundError",
  "resource": "Message",
  "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f"
}

`ConflictError` (409)

Returned when the request conflicts with existing state, such as a duplicate. resource names the conflicting resource, and id identifies it when applicable.

{
  "_tag": "ConflictError",
  "message": "A webhook with this URL already exists",
  "resource": "webhook"
}

`RateLimitedError` (429)

Returned when the organization exceeds its request rate limit. retryAfterSeconds tells you how long to wait before retrying.

{
  "_tag": "RateLimitedError",
  "retryAfterSeconds": 30
}

`FlagDisabledError` (403)

Returned when the request requires a feature that is not enabled for the organization. flag names the feature.

{
  "_tag": "FlagDisabledError",
  "flag": "campaigns"
}

`WebhookEnqueueError` (500)

Returned when a message was accepted but Samva could not enqueue its webhook delivery. The send itself succeeded; this reflects a transient failure in the webhook pipeline.

{
  "_tag": "WebhookEnqueueError",
  "reason": "Failed to enqueue webhook delivery"
}

`ExternalServiceError` (502)

Returned when an upstream provider returns an error. provider names the source.

{
  "_tag": "ExternalServiceError",
  "provider": "ses",
  "message": "Upstream provider rejected the request"
}

`BillingProviderError` (502)

Returned when the billing provider returns an error while resolving entitlements.

{
  "_tag": "BillingProviderError",
  "provider": "stripe",
  "message": "Billing provider request failed"
}

`InternalError` (500)

Returned for an unexpected server error. Retry with backoff; if it persists, contact support.

{
  "_tag": "InternalError",
  "message": "Internal server error"
}