Transactional SMS API Error Codes and Developer Troubleshooting Guide

Why error design matters

An API error is part of the developer contract. If every failure returns a generic 500 response, client developers cannot determine whether to correct their request, retry later or contact support.

A useful error model separates caller errors, authorization problems, throttling, temporary infrastructure failures and provider-specific outcomes.

HTTP status versus business error

HTTP status communicates the broad class of failure, while an application error code explains the specific condition.

For example, 400 can indicate invalid input, while INVALID_TEMPLATE_VARIABLE explains why the request was rejected. The exact codes should remain stable once published.

Authentication errors

Invalid or expired credentials should produce a predictable authentication response without revealing whether a particular secret exists.

Security-sensitive systems should also monitor repeated authentication failures.

Authorization errors

A caller may be authenticated but not authorized to use a sender, template or tenant resource. These should be distinguishable from authentication failure at the internal level while exposing only appropriate information externally.

Validation errors

Validation responses should identify the field or logical input that needs correction. Examples include invalid destination, missing template variable, unsupported sender or malformed schedule.

Do not expose internal database or provider implementation details in validation responses.

Rate-limit errors

A throttled client should know that the request was limited and, where appropriate, when it may retry. The response should be consistent with the gateway's documented rate-limit policy.

Temporary errors

Temporary database, queue or provider failures may justify retry. The API should distinguish these from permanent validation failures so client applications do not retry bad requests indefinitely.

Provider errors

Provider responses should be normalized into stable internal categories. Retain the original provider code for diagnostics but avoid forcing every application to understand provider-specific codes.

Idempotency conflicts

If an idempotency key is reused with different content, the API should return a clear conflict rather than silently replacing the original request. This prevents ambiguous customer communication.

Support diagnostics

Every error should be traceable using a request or correlation ID. Support should be able to locate the corresponding message, tenant and provider interaction without asking customers to resend sensitive information.

Error documentation

Publish a table of stable error codes, meaning, retry recommendation and corrective action. Include examples that show developers what to do next.

Implementation checklist

Define HTTP classes, stable error codes, retry guidance, provider normalization, idempotency conflicts, correlation IDs, documentation and monitoring.

Retry decision tree

A useful retry decision starts with the error class. Validation and authorization errors should normally not be retried. Rate-limit and temporary provider errors may be retried with backoff. Unknown submission outcomes require idempotency or reconciliation before another provider attempt.

Publishing this decision tree prevents every client application from inventing its own retry policy.

Error correlation

Return a request ID or correlation ID with errors. Internally connect that ID to the message ID, tenant, provider attempt and relevant log entries.

This gives support a safe way to investigate without requesting raw credentials or sensitive payloads from the customer.

Error response schema

A structured error can contain code, message, field where applicable, retryable flag or retry guidance, correlation ID and documentation reference. Keep the schema stable across API versions.

Provider timeout example

A worker sends a request to the provider and receives no response. It should not classify this automatically as rejected. The internal state can become SUBMISSION_UNKNOWN, after which reconciliation or a provider-supported idempotency mechanism determines the next action.

Monitoring error codes

Track error rates by stable internal code. A sudden increase in INVALID_TEMPLATE_VARIABLE points toward an application or template problem, while PROVIDER_THROTTLED indicates downstream capacity pressure.

Final developer checklist

Define stable error codes, HTTP mapping, retryability, correlation IDs, provider normalization, idempotency conflicts and troubleshooting documentation.

Error taxonomy

A useful taxonomy can separate CLIENT_INPUT, AUTHENTICATION, AUTHORIZATION, RATE_LIMIT, RESOURCE_STATE, TEMPORARY_INTERNAL, PROVIDER_RETRYABLE, PROVIDER_PERMANENT and UNKNOWN_SUBMISSION outcomes.

The names are illustrative; the important point is that the categories map to different developer actions.

Retryable versus safe-to-retry

A temporary error may be technically retryable but still unsafe to retry if the previous operation may have reached the provider. Safe retry therefore depends on both error category and operation state.

For message creation, idempotency makes retry safer. For provider submission, reconciliation may still be required.

HTTP 4xx guidance

Client-side 4xx errors generally require a request correction, permission change or waiting for quota reset. Clients should not implement blind exponential retries for every 4xx response.

Document exceptions such as 429 where retry after a delay may be appropriate.

HTTP 5xx guidance

A 5xx response can indicate a temporary service failure, but clients should use bounded retries with backoff. Excessive retries during an outage can make recovery harder.

The platform should provide a stable retry recommendation and correlation ID.

Provider failure mapping

Map provider failures into categories such as throttled, temporary unavailable, invalid sender, invalid destination or unknown outcome. Keep the original provider code and response metadata in protected diagnostic storage.

Support playbook

A support agent can start with the correlation ID, locate the request, inspect validation or authorization outcome, identify the message ID and then inspect provider attempts and callbacks.

This sequence avoids asking developers to reproduce production failures unnecessarily.

Error code governance

Treat error codes as public contract identifiers. Maintain a registry with description, first version, retryability, example and deprecation status.

Do not recycle an old code for a new meaning.

Error localization

API error codes should remain language-neutral and stable. Human-readable messages can change or be localized without forcing client logic to parse text.

Operational scenario

A client receives 409 IDEMPOTENCY_CONFLICT. The documentation explains that the same key was previously used with different content. The client stops retrying, retrieves the original request context and generates a new business event key only if a genuinely new notification is intended.

Final production checklist

Review error taxonomy, HTTP mapping, retry safety, provider normalization, support diagnostics, error-code governance and documentation examples.

Machine-readable error catalog

A machine-readable error catalog can complement human documentation. Each code can contain description, HTTP mapping, retry recommendation and the fields likely to cause the error.

This is particularly useful for SDK generation and automated client handling.

Error handling in SDKs

SDKs should expose structured errors rather than forcing developers to parse exception text. An SDK can classify retryable errors while leaving business decisions such as duplicate prevention to the application.

SDK behaviour should remain aligned with the public API contract.

Observability of failed requests

Track error rates by endpoint, tenant, client application and stable error code. This helps identify whether a problem is platform-wide or isolated to one integration.

Do not include sensitive payload values as metric labels because high-cardinality or personal data can create operational and privacy problems.

Final decision guide

Return stable errors that tell developers what happened and what action is safe. Keep diagnostic detail in protected logs, normalize provider failures and make retry behaviour explicit.

Error catalog example

A production catalog might define INVALID_DESTINATION as a permanent client correction, RATE_LIMITED as a temporary condition, PROVIDER_THROTTLED as a retryable downstream condition and SUBMISSION_UNKNOWN as an outcome requiring reconciliation rather than blind retry. The exact names can differ, but each code should have one predictable meaning.

Final troubleshooting sequence

Start with the correlation ID, identify the HTTP and application error, determine whether the request reached message creation, inspect any provider attempt and check whether idempotency or reconciliation is required. This sequence avoids repeated submissions while investigating a timeout.

Error handling rule

Do not let clients infer retryability from the human-readable message. Retry behaviour should be represented by stable documentation or structured metadata so wording can change without changing application logic.

Final note

Keep the public error contract stable and make every error actionable: correct the request, obtain permission, wait and retry safely, or investigate an uncertain outcome.

Implementation scenario

A developer receives HTTP 429 with RATE_LIMITED and a correlation ID. The client waits according to documented guidance and retries the same idempotent operation only when safe. If the next response is successful, the client continues using the returned message ID rather than creating a new notification.