Errors and rate limits

When a Slovio API request fails, you get an HTTP 4xx or 5xx status and a JSON body with a message that says what went wrong. Requests are also rate limited per API key, per minute. Over the limit you get HTTP 429, and you should wait and retry.

#What an error response looks like

Most errors use the same envelope as a successful response, with statusCode set to "10001":

{
  "statusCode": "10001",
  "status": 400,
  "message": "Invalid API key. Please check your API key and try again"
}

A 404 also includes url, the path you requested:

{
  "statusCode": "10001",
  "status": 404,
  "message": "Call not found",
  "url": "/v1/comms/calls/api-3f9c0b1e7d2a4c58b6e1f0a9d8c7b6a5e4d3c2b1"
}

#Validation errors

When a field is missing, has the wrong format, or is not allowed, you get HTTP 400 with a different shape: message plus an errors list. There is no statusCode or status key in this body.

{
  "message": "to must be E.164 format (e.g. +12025550100)",
  "errors": [
    {
      "message": "to must be E.164 format (e.g. +12025550100)",
      "path": "body.to"
    }
  ]
}

• path is one string, joined with dots. It starts with the part of the request that failed: body, query or params. For example body.to, body.variables.first name, or query.limit.
• message in each item is the validator's text for that field. The top-level message repeats the first one.
• If you send a field the endpoint does not accept, the path is body and the message starts with Unrecognized key(s) in object.

#Authentication errors

#Rate limits

Limits are counted per API key over a one-minute window. Every request counts, including ones that fail.

The 600 per minute for message sends is the platform default. It can be set higher for a single API key, for example for a high-volume OTP sender. Ask Slovio support if you need it. The call and broadcast limits are fixed.

Contacts, template lists and status lookups have no per-minute limit, but poll sensibly.

#Rate limit headers

Limited endpoints return these headers on every response:

RateLimit-Policy: 600;w=60
RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 42
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1790838660

RateLimit-Reset is seconds until the window resets. X-RateLimit-Reset is the same moment as a Unix time.

#The 429 response

Over the limit you get HTTP 429 with a Retry-After header in seconds. The body is plain text, not JSON:

Too many messages — please slow down and try again in a minute

The call endpoints say Too many call requests — please slow down and try again in a minute, and the broadcast endpoint says Too many broadcast requests — please slow down and try again in a minute.

#When to retry

• Retry 429 after the Retry-After time.
• Retry 5xx with exponential backoff, for example after 1 s, 2 s, then 4 s.
• Don't retry other 4xx errors. Fix the request first.
• Send an Idempotency-Key header on message sends and calls. A retry with the same key never sends or dials twice. See Send messages and Calls API.

#Common questions

#Why does my validation error have no statusCode?

Validation errors are returned before the request reaches the endpoint, so they use the shorter { "message", "errors" } shape. Check the HTTP status (400) rather than statusCode.

#What does "body.to" mean in the path?

It is the field that failed: to inside the request body. Paths are dot-joined, so a bad variable name in a call request looks like body.variables.first name.

#Can I get a higher limit than 600 messages per minute?

Yes. The limit for message and template sends can be raised for your API key. Contact Slovio support with your expected volume.

#Is the call placing limit the same as how fast calls go out?

No. 60 per minute is how many call requests the API accepts. Your calling line also paces calls. If it is busy you get a 400 saying Your calling line is busy — try again in N second(s).

#Do failed requests count toward the limit?

Yes. Every request in the window counts, so a loop of failing requests can use up your limit.