Error Reference

All error responses follow this shape:

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Request payload is invalid",
  "details": [
    { "field": "metadata.sellerTaxId", "reason": "sellerTaxId must be 13 digits" }
  ]
}

The details array is present only for VALIDATION_ERROR.

Error Codes

errorCode	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	API key does not have access to this resource
`VALIDATION_ERROR`	422	Request body or query parameters are invalid
`NOT_FOUND`	404	Resource not found
`INVALID_BASE64`	422	`pdfBase64` is not valid base64
`PDF_TOO_LARGE`	422	PDF exceeds size limit
`DUPLICATE_DOCUMENT`	409	Document number already exists for this source
`DUPLICATE_PAYMENT`	409	`sourcePaymentId` already exists
`DUPLICATE_RECEIPT`	409	Receipt already exists
`IDEMPOTENCY_CONFLICT`	409	Idempotency key reused with different request body
`TEMPLATE_NOT_FOUND`	422	No active PDF template for this document type
`PDF_GENERATION_FAILED`	422	Server failed to generate PDF from template
`INET_SUBMIT_FAILED`	502	Submission to INET e-Tax service failed
`PAYMENT_PROVIDER_NOT_CONFIGURED`	422	No payment provider configured for this source
`PAYMENT_PROVIDER_NOT_ALLOWED`	422	Specified provider not allowed for this source
`UNSUPPORTED_PAYMENT_PROVIDER`	422	Provider not supported
`WEBHOOK_SIGNATURE_INVALID`	401	Webhook HMAC signature is invalid
`RECEIPT_NOT_SHORT`	422	Convert-to-full called on a non-SHORT receipt
`RECEIPT_ALREADY_CONVERTED`	422	Receipt has already been converted
`RECEIPT_BUYER_TAX_INFO_REQUIRED`	422	Buyer tax ID required for full receipt
`INTERNAL_ERROR`	500	Unexpected server error — contact support

Handling Errors

# Check errorCode, not just HTTP status
response=$(curl -s -w "\n%{http_code}" ...)
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
error_code=$(echo "$body" | jq -r '.errorCode')

if [ "$error_code" = "IDEMPOTENCY_CONFLICT" ]; then
  # Generate a new idempotency key and retry
  echo "Conflict — retry with a new idempotency key"
fi