SubizDeveloper Docs
Get Started

API 4.0 · 4.1

Errors

Read API error responses, fix requests, and decide when to retry.

Read the HTTP status and JSON error body together. Token, account, and agent message allowances return HTTP 429. Invalid input, denied access, and some other operation-specific limits can return HTTP 400.

Error response

The following example shows selected fields from a payload-size error. The sizes are illustrative:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "payload_too_large,invalid_input,internal",
  "class": 400,
  "error": {
    "code": "payload_too_large,invalid_input,internal",
    "attrs": {
      "current_size": {
        "type": "number",
        "value": "2049"
      },
      "maximum_size": {
        "type": "number",
        "value": "2048"
      }
    }
  }
}
Field How to use it
error.code Comma-separated error codes. Split on commas and match individual values.
error.message Human-readable messages, commonly keyed by en_US and vi_VN. Do not use message text for program logic.
error.attrs Optional details such as a field name, current size, or maximum size. Each value has a type and a string value; numeric values are encoded as strings.
error.id Error occurrence identifier, when present. Include it in a support report.
error.number Diagnostic grouping code, when present. Include it alongside the ID.
Top-level code Repeats the error codes in the standard response envelope.
Top-level class Legacy classification. Use the actual HTTP status and error codes instead.

The gateway can append internal to a more specific error. Its presence alone does not mean a request is safe to retry. In the example above, reduce the attribute size first.

Common error codes

This is a practical subset, not an exhaustive list. A response can contain several of these codes.

Code What to do
invalid_input Check the JSON body, required fields, and value types.
invalid_field Correct the named field, such as an unsupported message format.
access_deny Check the token’s account and the issuing agent’s permissions or conversation access.
access_token_expired Create a replacement token and update your integration.
locked_agent, locked_account Ask an account administrator to check the agent or account status.
missing_resource Check the resource ID and account. Repeating the same request will not create the missing resource.
conversation_ended Check the conversation state before sending an ordinary message.
invalid_integration Check that the conversation’s channel integration is still connected.
payload_too_large Reduce the data identified by the error. See Usage limits.
limit_exceeded Check the affected count or capacity. Waiting does not fix a structural limit.
rate_limit Slow down. Token, account, and agent message limits return HTTP 429 with Retry-After in seconds; daily exhaustion requires waiting until 00:00 UTC.
service_unavailable, timeout, retryable Treat as potentially temporary; follow the retry guidance below.

For authentication problems, test the token with /4.1/me. A successful token check does not grant access to every operation.

HTTP status codes

Status Handling
400 Inspect error.code. Authentication, permissions, validation, and some limits use this status.
429 Token or account usage limit, or another throttle. Honor Retry-After and reduce traffic. The body’s legacy class may still be 400.
500 Server failure. The standard gateway uses this for service_unavailable, among other failures.

Also handle other non-success statuses and network failures. A proxy or failed connection may return an empty or non-JSON body. Keep the status and a sanitized response excerpt instead of failing while parsing the error.

When to retry

  • Invalid data or denied access: fix the request, token, or permissions first.
  • Rate limiting: queue the work and use delayed retries.
  • Temporary failure on a read: use increasing delays with jitter and a fixed attempt limit.
  • Timeout or lost response on a write: the operation may have succeeded. Check the resulting state before resubmitting.

For a message send, inspect message history or received webhook events. If the outcome remains unclear, stop automatic retries and reconcile it. Do not assume every endpoint supports an idempotency key.

Get help

Include the HTTP method and endpoint, request time with timezone, status, and error.code. Add error.id and error.number if available. Share only the relevant, sanitized request fields; never include the access token.