REST API error catalog

Documentation for integrators

Understand the problem and what to do next, from authentication to message sending.

17problem types

20message rejection descriptions

3operation result formats

Error types

Problem statusAll statusesHTTP 400HTTP 401HTTP 403HTTP 404HTTP 405HTTP 409HTTP 415HTTP 422HTTP 500Search causes or typesClear17 types

Resource not foundThe endpoint, message, page or sender is not available for this account.

HTTP 404

Internal server errorAn internal server error occurred while processing the operation.

HTTP 500

Authentication failedThe API token is missing or cannot be used to authenticate the request.

HTTP 401

Access deniedThe account, REST settings, client IP address or permissions prevent this operation.

HTTP 403

Invalid request bodyThe request body is missing or cannot be processed as the expected JSON.

HTTP 400

Bad requestThe request does not match an operation described in the API specification.

HTTP 400

Missing request parameterMessage IDs were not provided for retrieval, cancellation or deletion.

HTTP 400

Invalid parameter formatThe ID list contains a value that is not a numeric message ID.

HTTP 400

Sender already existsThe sender name is already assigned to the account or matches a system sender.

HTTP 409

Validation failedThe data does not meet schema constraints or value rules, such as sender name requirements.

HTTP 400HTTP 422

Missing body dataThe request is missing messages to send or price, or a description of the sender name's intended use.

HTTP 400

Invalid parameter valuePath parameter validation rejected a value in the request URL.

HTTP 400

Method not allowedThe endpoint exists but does not support the submitted HTTP method.

HTTP 405

Message cannot be canceledThe message is already canceled or is not in a state that allows cancellation.

Item status 409

Sender cannot be removedA protected system sender cannot be deleted.

HTTP 403

Sender is not activeThe sender is not in a state that allows it to be set as default.

HTTP 409

Unsupported media typeThe Content-Type specifies a format that this endpoint does not accept.

HTTP 415

How to read a response

1. Check HTTP and Content-Type. A failure of the whole request has its own HTTP status and an application/problem+json object.
2. Identify the type. type identifies the problem, detail describes the occurrence, and instance provides the request path.
3. Read the operation result. With HTTP 200, check the message status, pricing result or cancellation/deletion result of every item.

Response headers

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

Example API response

{
    "type": "https://api.szybkisms.pl/problems/forbidden/",
    "status": 403,
    "title": "Access Denied",
    "detail": "Your account has not been verified by the operator yet.",
    "code": "403-2",
    "instance": "/rest/messages/sms"
}

What is code used for?

code is a diagnostic code that helps support locate the error handling branch. For example, 403-2 consists of problem status 403 and internal number 2. In a batch, an item’s problem status can differ from the HTTP status of the whole response.

When reporting a problem, provide code, the endpoint and request time. Classify problems in an integration using type and the problem status. The number after the hyphen is not a public cause registry.

Operation results in batch responses

Sending returns a message status, pricing returns a calculation result, and cancellation or deletion returns the result of an operation on a resource. Each format describes its operation; HTTP 200 confirms that the request was processed.

Message sending and statusesQueue acceptance, rejection and subsequent delivery status.

Message pricingPrice calculation results and reasons for unsuccessful pricing.

Cancellation and deletionOperation status and Problem Details for individual failures.

Full REST API documentation · JSON catalog · Problem Details standard — RFC 9457