Skip to main content

Errors

Inttegro uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range signal client errors that require action on your end, and codes in the 5xx range indicate server errors on Inttegro's infrastructure (these are rare).

When a request fails, the API returns a structured error object with diagnostic information to help you identify and resolve the problem. All error responses follow a consistent format across every endpoint, making error handling predictable and straightforward to implement.

For a centralized lookup table of endpoint-specific error.code values and corrective actions, see Error Codes.

Read the explanation, not just the label

Every public error has two human-readable fields with different jobs:

  • message states why this request was rejected or could not finish.
  • detail explains the relevant safety rule or prerequisite and what to do next.

Neither field contains internal service names, storage details, or raw dependency errors. Unclassified failures remain intentionally general, but they still tell you whether to retry, refresh state, change the request, or contact support. Keep the response's request id when contacting support.

HTTP status codes

Inttegro returns standard HTTP status codes to indicate the outcome of your API request:

  • Name
    200 - OK
    Description

    The request succeeded. The response body contains the requested resource or confirms the operation completed.

  • Name
    400 - Bad Request
    Description

    The request is malformed or missing required parameters. Check your request syntax and ensure all required fields are present.

  • Name
    401 - Unauthorized
    Description

    Authentication failed. Your API key is missing, invalid, or has been revoked. Verify you're sending a valid key in the Authorization header.

  • Name
    403 - Forbidden
    Description

    Your API key lacks permission to perform this operation. Verify that the key has access to the requested resource or action.

  • Name
    404 - Not Found
    Description

    The requested resource doesn't exist. Verify the resource ID.

  • Name
    409 - Conflict
    Description

    Another operation updated or claimed the resource before this request could safely apply its change. Fetch the latest resource state before deciding what to do next. For payment conflicts, see payment_transition_conflict.

  • Name
    422 - Unprocessable Entity
    Description

    The request is well-formed but violates business logic constraints. This is the most common error—the parameters are syntactically valid but semantically incorrect for the current operation.

  • Name
    429 - Too Many Requests
    Description

    You've exceeded the rate limit. Back off exponentially and retry after the delay specified in the Retry-After header.

  • Name
    500, 502, 503, 504 - Server Errors
    Description

    Something went wrong on Inttegro's servers. These are rare and usually transient. Retry the request with exponential backoff.

Error response structure

When an API request fails, Inttegro returns a JSON response with a single error key containing structured diagnostic information. This consistent format lets you build unified error handling across all endpoints.

The error object always includes code, type, and url. Normalized endpoint errors also include a plain-language message, an actionable detail, and machine-readable cause and fix_code values.

Important: Error copy is caller-safe and excludes raw dependency or storage errors, but it is written for developers and integrators rather than shoppers. Use code and fix_code to choose customer-facing copy in your application instead of displaying the API response verbatim.

Error response

SDK versionv8.2.0
ErrorResponse {
  error: { … },
}

The error object

Every error response contains an error object with the following attributes:

Attributes​

  • Name
    cause
    Type
    string
    Description

    The underlying category of failure—identifies which system or validation rule triggered the error. Common values include authentication_failed, authorization_failed, invalid_request_parameter, and missing_request_parameter. This field groups related errors into broad categories.

    • Route errors to appropriate handlers based on failure type
    • Identify patterns in error categories across requests
    • Determine whether the error is retriable (transient) or requires user action
    • Build monitoring dashboards grouped by failure category
    • Implement different retry strategies based on error type
  • Name
    code
    Type
    string
    Description

    A unique machine-readable identifier for this specific error condition. Unlike type and cause, which group errors into categories, code pinpoints the exact problem—for example, payment_method_expired versus payment_method_not_found. Always present in every error response.

    • Implement precise error handling logic for specific failure scenarios
    • Map error codes to user-friendly messages in your application
    • Track and alert on specific error codes in monitoring systems
    • Document common errors and resolutions in internal runbooks
    • Build automated remediation for known error conditions
  • Name
    detail
    Type
    string
    Description

    A comprehensive explanation of what went wrong and the next safe action. This field provides more depth than message without exposing internal dependencies, storage details, or raw underlying errors.

    • Debug integration issues during development with detailed diagnostics
    • Log comprehensive error information for post-mortem analysis
    • Understand the specific constraint or validation rule that failed
    • Provide detailed feedback to engineers investigating issues
    • Identify which request parameters caused the error
  • Name
    fix_code
    Type
    string
    Description

    A machine-readable suggestion for how to resolve the error. This field translates the problem into a specific action—for example, change_request_parameters, repeat_same_request, or contact_customer_support.

    • Implement automated recovery strategies in error handling code
    • Surface specific remediation steps to operations teams
    • Build self-healing systems that resolve certain errors automatically
    • Create decision trees for triaging and resolving errors
    • Generate actionable alerts with clear next steps
  • Name
    message
    Type
    string
    Description

    A concise, human-readable description of the error. This is the primary error message you'll typically log for quick diagnostics. It's shorter and more focused than detail, providing a summary of what went wrong.

    • Log error summaries for quick pattern recognition
    • Generate alerts and notifications with clear context
    • Provide immediate diagnostics without reading full details
    • Create error tracking entries in monitoring systems
    • Assist support teams in identifying common issues
  • Name
    type
    Type
    string
    Description

    Categorizes the error into broad classes to help clients determine retry strategies. Common values include invalid_request_parameter, transient_error, and unknown_error. This field indicates whether an error is due to client input issues or system-level problems. Always present in every error response.

    • Determine whether to retry the request or fix client-side input
    • Implement different retry strategies based on error class
    • Build monitoring alerts grouped by error type
    • Route errors to appropriate handling code paths
    • Distinguish between transient failures and permanent errors
  • Name
    url
    Type
    string
    Description

    A link to the error reference documentation for this specific error code. This URL points to a detailed explanation of the error, common causes, and step-by-step resolution guidance. Always present in every error response.

    • Direct engineers to comprehensive troubleshooting resources
    • Link error logs to documentation for faster resolution
    • Provide support teams with authoritative information
    • Build in-app help systems that deep-link to relevant documentation
    • Reduce time-to-resolution for common integration issues

Error types

The type field categorizes errors into broad classes that guide your retry and recovery strategy. Use this field to determine whether an error is due to invalid client input or a transient system issue.

  • Name
    invalid_request_parameter
    Description

    The request failed due to invalid or incorrectly formatted parameters. This error type signals that you must modify the request before retrying—the same request will always fail without changes to input data. Review the detail and cause fields to identify which parameters need correction. View details →

  • Name
    transient_error
    Description

    A temporary failure that may succeed if retried. These errors occur due to momentary system load, network issues, or resource contention that is expected to resolve quickly. Implement retry logic with exponential backoff—most transient errors resolve within seconds to minutes. View details →

  • Name
    unknown_error
    Description

    An unexpected failure that doesn't fit established error categories. These errors are typically logged for investigation and may represent edge cases or system issues that require engineering attention. Contact support if you encounter these errors repeatedly. View details →

Fix codes

The fix_code field provides machine-readable guidance on how to resolve the error. Use this field to implement automated recovery strategies or surface specific remediation steps to your team.

  • Name
    abandon_request
    Description

    The request cannot succeed and should be abandoned entirely. This typically signals a fundamental constraint violation where no modification or retry strategy will resolve the problem. Log the error for investigation and inform the user that the operation cannot be completed. View details →

  • Name
    change_request_parameters
    Description

    The request parameters are invalid and must be corrected before retrying. Examine the detail field for specific parameter issues, update the request with valid values, then resubmit. This is the most common fix code for validation failures. View details →

  • Name
    contact_customer_support
    Description

    The error requires manual intervention from Inttegro support. This occurs for account-level issues, configuration problems, or edge cases that cannot be resolved through API calls alone. Contact support with the complete error response and context about your integration. View details →

  • Name
    repeat_same_request
    Description

    The request should be retried without modification. This signals a transient failure where the same request is expected to succeed on retry. Use exponential backoff to avoid overwhelming the system during recovery—start with a 1-second delay and double after each attempt. View details →

  • Name
    satisfy_precondition
    Description

    A required precondition must be satisfied before the requested operation can proceed. Examine the detail field to identify which precondition failed, complete the necessary prerequisite action, then retry the operation. Common examples include sealing an order before payment or verifying a resource exists before operating on it. View details →

Error causes

The cause field identifies the underlying category of failure—which system or validation rule triggered the error. Use this field to route errors to appropriate handlers and identify patterns across requests.

  • Name
    authentication_failed
    Description

    Authentication failed due to missing, invalid, or expired credentials. Verify your API key is correct, properly formatted in the Authorization header, and hasn't been revoked or expired. This is a permanent failure that requires credential correction. View details →

  • Name
    authorization_failed
    Description

    Your API key is valid but does not allow this operation. Verify that the key has the required permissions. View details →

  • Name
    invalid_request_parameter
    Description

    One or more request parameters contain invalid values that violate format, type, or business logic constraints. Check the detail field for specific parameter issues and correct the values before retrying. This is the most common error cause. View details →

  • Name
    missing_request_parameter
    Description

    Required request parameters were not provided. Review the API documentation for the endpoint to identify which parameters are mandatory, then include them in your request and retry. The detail field specifies which parameters are missing. View details →

  • Name
    precondition_unmet
    Description

    A required precondition must be satisfied before the requested operation can proceed. Examine the error detail to identify which precondition failed, complete the necessary prerequisite action, then retry the operation. View details →

  • Name
    unknown
    Description

    The error cause could not be determined. This occurs for unexpected failures that don't map to known categories. Log these errors with full context for investigation as they may represent edge cases requiring code changes. Contact support if you encounter these errors frequently. View details →