Skip to main content

Troubleshooting API requests

FAQ Author
Updated

Use the HTTP status, response body, and request ID to diagnose a failed API request.

Check the response

  1. Record the HTTP method and path without credentials or personal data.
  2. Record the HTTP status and JSON error response.
  3. Record the X-Request-Id response header when it is present.
  4. Compare the request with the API reference.

Common statuses are:

Status Meaning What to check
400 Invalid request Required fields, field formats, query parameters, and JSON types.
401 Authentication failed Bearer header, token expiry, client credentials, and the organisation used to issue the token.
404 Resource or route not found HTTP method, /v1.1/ path, resource identifier, and resource ownership.
503 Service unavailable Retry read-only requests with backoff. Check the outcome before retrying a request that changes data.
500 Internal error Do not repeatedly retry a non-idempotent request until you know whether it succeeded.

Use request IDs safely

The API generates a request ID for tracing and returns X-Request-Id on most endpoint responses. Log that header with the status, method, and path.

Do not log access tokens, client secrets, message content, or full phone numbers with a request ID.

Retry safely

  • Retry read-only GET requests with exponential backoff for temporary 5xx failures.
  • Before retrying a failed order or other state-changing request, check whether the original request succeeded.
  • Do not retry POST /v1.1/sms automatically after a timeout or unknown response. It has no idempotency key, so a retry can send and charge another message.
  • Do not retry 400, 401, or 404 without changing the request.

Contact support

If the request still fails, include the UTC timestamp, method, path, HTTP status, safe error text, and X-Request-Id. If the header is absent, include the timestamp and path instead.

Related articles

Comments

0 comments

Please sign in to leave a comment.