Errors

One RFC 9457 problem shape for every endpoint, and the status codes.

Errors use RFC 9457 Problem Details, with the content type `application/problem+json`. One shape across the API, so you write one error handler instead of one per call. A few older voice endpoints are the exception and say so on their own page.

{
  "type": "https://docs.cloudshope.com/errors/sms/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Phone must be exactly 10 digits",
  "instance": "/api/v1/crm/workspaces/8/leads/create",
  "trace_id": "b0f7c1e2-5a1d-4c8e-9f3a-2d6b7c8e9f01",
  "errors": [
    { "field": "phone", "code": "invalid_string", "message": "Phone must be exactly 10 digits" }
  ]
}

422 — a validation failure. `errors` is present only on a 422.

Fields

Field	Meaning
type	A URL identifying the kind of error. Stable — safe to branch on.
title	A short, human label for the type.
status	The HTTP status code, repeated in the body.
detail	A human-readable explanation for this specific occurrence.
instance	The request path that produced the error.
trace_id	Unique per response. Quote it to support. Also returned as the `x-request-id` header.
errors	Field-level failures, on a 422 only: `field`, `code`, `message`.

Status codes

Status	Meaning
400 bad-request	The request was understood but cannot be processed as sent — e.g. a template that is not approved, no recipients resolved.
401 unauthorized	Missing, malformed, invalid or expired token.
403 forbidden	Authenticated, but not permitted to perform this action.
404 not-found	No such resource on this account.
409 insufficient-credit	Not enough credit on the account to send this campaign.
422 validation-failed	A field failed validation. See `errors`.
429 rate-limited	Too many requests. Wait `Retry-After` seconds. Applies to the WhatsApp endpoints.
500 internal-error	Something went wrong on our side. Safe to retry with backoff.