Skip to main content

Error Structure

When an error occurs, the API returns a standardized response:
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "method": "POST",
  "url": "/v4/i/pix/in/dynamic-qrcode",
  "status": 400,
  "success": false,
  "message": "Error description",
  "hint": "Suggestion for correction",
  "code": "VALIDATION_ERROR",
  "codeMessage": "Additional details"
}
FieldTypeDescription
requestIdstringUnique UUID for tracking
statusnumberHTTP code
successbooleanAlways false on errors
messagestringHuman-readable error description
hintstringSuggestion on how to resolve
codestringProgrammatic error code

HTTP Codes

Success (2xx)

CodeNameDescription
200OKRequest successful
201CreatedResource created successfully

Client Errors (4xx)

CodeNameDescription
400Bad RequestMalformed request or invalid parameters
401UnauthorizedMissing or invalid credentials
403ForbiddenIP not allowed or access denied
404Not FoundResource not found
409ConflictIdempotency or state conflict
422Unprocessable EntityValid data but not processable
429Too Many RequestsRate limit exceeded

Server Errors (5xx)

CodeNameDescription
500Internal Server ErrorInternal error (contact support)
502Bad GatewayService temporarily unavailable
503Service UnavailableMaintenance or overload
504Gateway TimeoutExternal service timeout

Specific Error Codes

Authentication

CodeHTTPDescriptionSolution
UNAUTHORIZED401Invalid credentialsCheck API Key and Secret
API_KEY_NOT_FOUND404API Key doesn’t existGenerate a new credential
IP_NOT_ALLOWED403IP not in allowlistAdd your IP in the dashboard

Validation

CodeHTTPDescriptionSolution
VALIDATION_ERROR400Required field missingCheck required fields
INVALID_AMOUNT400Invalid valueUse positive number
INVALID_PIX_KEY400Invalid PIX keyCheck key format
INVALID_CPF_CNPJ400Invalid CPF/CNPJUse numbers only

PIX IN

CodeHTTPDescriptionSolution
QRCODE_EXPIRED400QR Code expiredGenerate a new QR Code
QRCODE_NOT_FOUND404QR Code doesn’t existCheck the txId
REFUND_NOT_ALLOWED400Refund not allowedCheck refund deadline
INSUFFICIENT_BALANCE400Insufficient balanceDeposit more funds

PIX OUT

CodeHTTPDescriptionSolution
TRANSFER_FAILED400Transfer failedCheck recipient data
PIX_KEY_NOT_FOUND404PIX key doesn’t existConfirm key with recipient
DAILY_LIMIT_EXCEEDED400Daily limit exceededWait for next day
BLOCKED_RECIPIENT403Blocked recipientContact support

BACEN/SPI Codes

Errors returned by the Brazilian Central Bank’s Instant Payment System (SPI):
CodeCategoryMeaningDescription
AB03SettlementSPI TimeoutSettlement interrupted by timeout in the Instant Payment System
AB09SettlementReceiver participant errorError at the receiver’s PSP (bank) when processing the request
AC03AccountInvalid account numberReceiver’s branch and/or account does not exist or is invalid
AC06AccountBlocked accountSpecified account is blocked for transactions
AC07AccountClosed accountTransactional account closed at the Receiver’s PSP
AC14AccountInvalid account typeIncorrect type for the specified transactional account
AG03OperationUnsupported transactionTransaction type not supported/authorized for the account
AM02AmountValue exceeds limitValue exceeds the limit allowed for the account type
AM09AmountValue mismatchRefund amount exceeds the original payment order
BE01IdentificationInconsistent CPF/CNPJCPF/CNPJ not consistent with account holder
BE17IdentificationQR Code rejectedQR Code rejected by the receiver’s participant
CH11CPF/CNPJIncorrect CPF/CNPJReceiver’s CPF/CNPJ is incorrect or invalid
DS04ProcessingOrder rejected by receiverRejected by the Receiver’s PSP for operational reasons
DS24ProcessingAuthorization timeoutTimeout between PAIN.013 and PACS.008 (recurring authorization)
DT05DateInvalid or expired dateInvalid or expired cut-off date
RR04RegulationRegulatory reasonRejection due to regulatory compliance or legal requirements
SL02SettlementInvalid account numberInvalid account for settlement
These codes are defined by the Central Bank of Brazil and may be returned in PIX operations involving communication with other banks.

Webhooks

CodeHTTPDescriptionSolution
WEBHOOK_NOT_FOUND404Webhook doesn’t existCheck configId
INVALID_URL400Invalid URLUse valid HTTPS
DUPLICATE_WEBHOOK409Duplicate webhookUse different URL

Rate Limiting

CodeHTTPDescriptionSolution
RATE_LIMIT_EXCEEDED429Too many requestsWait and implement backoff

Error Handling

JavaScript Example

async function callOwemAPI(endpoint, options) {
  try {
    const response = await fetch(`https://api.owem.com.br${endpoint}`, options)
    const data = await response.json()

    if (!data.success) {
      switch (data.status) {
        case 401:
          throw new Error("Invalid credentials")
        case 403:
          throw new Error("IP not allowed")
        case 429:
          // Implement exponential backoff
          await sleep(getBackoffDelay(data))
          return callOwemAPI(endpoint, options)
        default:
          throw new Error(data.message)
      }
    }

    return data
  } catch (error) {
    console.error(`[Owem API] ${error.message}`)
    throw error
  }
}

Python Example

import requests
import time

def call_owem_api(endpoint, **kwargs):
    try:
        response = requests.request(
            url=f"https://api.owem.com.br{endpoint}",
            **kwargs
        )
        data = response.json()

        if not data.get("success"):
            status = data.get("status")

            if status == 429:
                # Exponential backoff
                time.sleep(get_backoff_delay(data))
                return call_owem_api(endpoint, **kwargs)

            raise Exception(data.get("message"))

        return data

    except requests.RequestException as e:
        print(f"[Owem API] {e}")
        raise

Best Practices

Log Request IDs

Always log the requestId to facilitate debugging with support.

Exponential Backoff

Implement retry with exponential backoff for 429 and 5xx errors.

Circuit Breaker

Use circuit breaker to avoid cascading failures.

Monitoring

Monitor error rate and latency per endpoint.