Error Codes Reference

Complete reference of GoRoute API error codes and how to resolve them.

HTTP Status Codes

Success Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
202	Accepted	Request accepted for processing
204	No Content	Request successful, no content to return

Client Error Codes

Code	Meaning	Description	Action
400	Bad Request	Invalid request format or parameters	Fix request and retry
401	Unauthorized	Invalid or missing API key	Check API key
403	Forbidden	Insufficient permissions	Contact support
404	Not Found	Resource doesn't exist	Check ID/endpoint
405	Method Not Allowed	Wrong HTTP method	Use correct method
409	Conflict	Resource conflict (duplicate)	Use different ID
415	Unsupported Media Type	Wrong Content-Type	Set correct header
422	Unprocessable Entity	Validation failed	Fix data and retry
429	Too Many Requests	Rate limit exceeded	Wait and retry

Server Error Codes

Code	Meaning	Description	Action
500	Internal Server Error	Unexpected error	Retry, contact support if persists
502	Bad Gateway	Upstream service error	Retry after delay
503	Service Unavailable	Temporarily unavailable	Retry after delay
504	Gateway Timeout	Request timed out	Retry with smaller payload

API Error Codes

Authentication Errors (AUTH_xxx)

Code	Message	Description	Resolution
AUTH_001	Invalid API key	API key is malformed or invalid	Check API key format
AUTH_002	API key expired	API key has been revoked	Generate new key in dashboard
AUTH_003	API key disabled	Key temporarily disabled	Contact support
AUTH_004	Insufficient permissions	Key lacks required scope	Request permission upgrade
AUTH_005	IP not allowed	Request from unauthorized IP	Add IP to allowlist

{
    "error": {
        "code": "AUTH_001",
        "message": "Invalid API key",
        "details": "The provided API key does not match any active keys"
    }
}

Validation Errors (VAL_xxx)

Code	Message	Description	Resolution
VAL_001	Invalid XML	XML is malformed	Fix XML syntax
VAL_002	Schema validation failed	Doesn't match UBL schema	Fix structure
VAL_003	Schematron error	Business rule violation	Fix business rule
VAL_004	Invalid identifier	Peppol ID format wrong	Check scheme/ID format
VAL_005	Invalid document type	Unsupported document type	Use supported type
VAL_006	Invalid date format	Date not ISO 8601	Use YYYY-MM-DD
VAL_007	Amount mismatch	Totals don't calculate	Fix line/tax totals
VAL_008	Missing required field	Required field empty	Add required field
VAL_009	Invalid currency	Currency code invalid	Use ISO 4217 code
VAL_010	Invalid country code	Country code invalid	Use ISO 3166-1 alpha-2

{
    "error": {
        "code": "VAL_003",
        "message": "Schematron validation failed",
        "details": [
            {
                "rule": "BR-16",
                "severity": "error",
                "message": "Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110)",
                "location": "/Invoice/cac:LegalMonetaryTotal"
            }
        ]
    }
}

Participant Errors (PART_xxx)

Code	Message	Description	Resolution
PART_001	Participant not found	Not registered on Peppol	Verify identifier
PART_002	Participant not active	Registration inactive	Contact recipient
PART_003	Invalid scheme	Scheme not recognized	Use valid scheme code
PART_004	Capability not supported	Document type not supported	Check SMP registration
PART_005	SMP lookup failed	Could not query SMP	Retry, contact support

{
    "error": {
        "code": "PART_001",
        "message": "Participant not found",
        "details": {
            "scheme": "0192",
            "identifier": "123456789",
            "suggestion": "Verify the identifier with the recipient"
        }
    }
}

Transaction Errors (TX_xxx)

Code	Message	Description	Resolution
TX_001	Duplicate transaction	Transaction ID already exists	Use different ID
TX_002	Transaction not found	Transaction ID doesn't exist	Check transaction ID
TX_003	Transaction expired	Transaction too old to modify	Create new transaction
TX_004	Invalid state	Cannot perform action in current state	Wait or check status
TX_005	Delivery failed	Document could not be delivered	Check error details
TX_006	Timeout	Processing timed out	Retry

{
    "error": {
        "code": "TX_005",
        "message": "Delivery failed",
        "details": {
            "transaction_id": "tx_abc123",
            "reason": "Recipient endpoint returned HTTP 500",
            "attempts": 3,
            "last_attempt": "2024-01-15T10:30:00Z"
        }
    }
}

Organization Errors (ORG_xxx)

Code	Message	Description	Resolution
ORG_001	Organization not found	Org ID doesn't exist	Check organization ID
ORG_002	Organization suspended	Account suspended	Contact support
ORG_003	Quota exceeded	Monthly quota reached	Upgrade plan
ORG_004	Feature not available	Feature not in plan	Upgrade plan

Document Errors (DOC_xxx)

Code	Message	Description	Resolution
DOC_001	Document too large	Exceeds size limit	Reduce size or use batch
DOC_002	Attachment too large	Attachment exceeds limit	Reduce attachment size
DOC_003	Invalid attachment type	MIME type not supported	Use supported type
DOC_004	Document not found	Document ID not found	Check document ID

Schematron Error Codes

EN16931 (European Standard)

Rule	Description
BR-01	An Invoice shall have a Specification identifier
BR-02	An Invoice shall have an Invoice number
BR-03	An Invoice shall have an Invoice issue date
BR-04	An Invoice shall have an Invoice type code
BR-05	An Invoice shall have an Invoice currency code
BR-06	An Invoice shall have a Seller name
BR-07	An Invoice shall have a Buyer name
BR-16	Total amount with VAT = Total without VAT + VAT amount

Peppol BIS 3.0

Rule	Description
PEPPOL-EN16931-R001	Document MUST have business process identifier
PEPPOL-EN16931-R002	Document MUST have specification identifier
PEPPOL-EN16931-R003	Document type code MUST be a valid Peppol code
PEPPOL-EN16931-R007	ProcessID MUST be valid
PEPPOL-EN16931-R120	Scheme ID must be from code list

XRechnung (Germany)

Rule	Description
BR-DE-1	Buyer reference MUST be provided
BR-DE-2	Leitweg-ID format MUST be correct
BR-DE-5	Bank account MUST be IBAN format
BR-DE-15	Country code MUST be provided

Error Response Format

All errors follow this structure:

{
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable message",
        "details": {
            // Additional context
        },
        "request_id": "req_abc123",
        "documentation_url": "https://docs.goroute.ai/errors/ERROR_CODE"
    }
}

Handling Errors

Python Example

def handle_api_error(response):
    """Handle GoRoute API errors."""
    
    if response.status_code == 200:
        return response.json()
    
    error = response.json().get("error", {})
    code = error.get("code", "UNKNOWN")
    message = error.get("message", "Unknown error")
    
    if code.startswith("AUTH_"):
        raise AuthenticationError(message)
    elif code.startswith("VAL_"):
        raise ValidationError(message, error.get("details"))
    elif code.startswith("PART_"):
        raise ParticipantError(message)
    elif code.startswith("TX_"):
        raise TransactionError(message)
    elif response.status_code == 429:
        raise RateLimitError(message)
    elif response.status_code >= 500:
        raise ServerError(message)
    else:
        raise APIError(message)

JavaScript Example

async function handleApiError(response) {
    if (response.ok) {
        return response.json();
    }
    
    const error = await response.json();
    const { code, message, details } = error.error;
    
    switch (code?.split('_')[0]) {
        case 'AUTH':
            throw new AuthenticationError(message);
        case 'VAL':
            throw new ValidationError(message, details);
        case 'PART':
            throw new ParticipantError(message);
        case 'TX':
            throw new TransactionError(message);
        default:
            throw new APIError(message);
    }
}

Next Steps

• Webhook Events
• Error Recovery
• Support