API errors

Spirius APIs answer every error as JSON (application/json) with the same members:

{
  "code": "VALIDATION_ERROR",
  "message": "Validation error in request data",
  "details": {
    "errors": [
      { "field": "batch.sms_config.sender_id", "description": "Field required", "reason": "missing" }
    ]
  }
}

details members:

The error codes below are shared by all Spirius APIs. Each API reference lists every code that API answers with, including codes of its own.

A refused or failed request is never counted against the client's quota and never billed.

Some older APIs still answer in their earlier format; their API reference describes it.

Shared error codes​

VALIDATION_ERROR​

The API could not accept the request as sent. A field is missing or has the wrong type or format, a value is outside its allowed range, or the request breaks a rule the API reference describes. details.errors lists each failing input. An API may answer with a more specific code for the same kind of error; its API reference lists them.

Fix each input details.errors or the message names, then send the request again. Do not retry the request unchanged; the answer will be the same.

UNAUTHORIZED​

The request carried no credentials, or the API did not accept the ones it carried. They may be wrong, expired or revoked, or sent with an authentication scheme the API does not accept. The message is the same in every case, and the WWW-Authenticate header names the scheme the API accepts.

Check that the request uses the authentication scheme the API reference describes, and that the credentials are the current ones for the environment you call (test or production). Do not retry without changing the credentials.

CALLER_IP_NOT_ALLOWED​

The client restricts the IP addresses that may call the API, and the request came from another one. Call from an allowed address, or add the address to the client's allowed addresses.

CALLER_NOT_ALLOWED​

The client is not enabled for this API. The API does not say why. Contact your Spirius account manager.

SCOPE_NOT_GRANTED​

The resource needs a scope the client's credentials do not grant. The message names the scope. Contact your Spirius account manager.

NOT_FOUND​

No resource exists at the path of the request. Check the path against the API reference, including the version segment, and check that the base URL is the one for your environment (test or production).

METHOD_NOT_ALLOWED​

The path exists, but not for the HTTP method of the request. Use the method the API reference gives for the path.

RATE_LIMITED​

The client sent requests faster than its agreed rate. The Retry-After header gives the number of seconds to wait. Spread requests over time instead of sending them in bursts; if your traffic needs a higher rate, contact your Spirius account manager.

QUOTA_EXCEEDED​

The client has used up the quota agreed for the current period. The Retry-After header gives the time the quota resets, as an HTTP date or as a number of seconds. To raise the quota, contact your Spirius account manager.

INTERNAL_ERROR​

The request failed because of an unexpected error on the Spirius side. The message does not describe the cause. Try again later; if it keeps failing, contact Spirius support with the request path and the time of the request.

PROVIDER_UNAVAILABLE​

A provider the API depends on could not be reached, or did not answer in time. Wait for the Retry-After seconds, then send the request again.

SERVICE_UNAVAILABLE​

The service could not complete the request right now. Wait for the Retry-After seconds, then send the request again.

A 403 or 429 without a code​

A 403 or 429 whose body is not JSON with a code member comes from the Spirius network edge, before the request reaches the API. The credentials were not checked.

• 403: the calling address is not allowed there, or the request matched a security rule. Contact Spirius support with the calling IP address and the time of the request.
• 429: the edge limits how fast one address may call. Slow down and try again after a few minutes.