---
title: "Errors"
description: "Understand API error responses, HTTP status codes, and how to handle failures in your integration."
canonical: "https://studio.inttegro.com/api/errors"
format: inttegro-machine-docs/v1
language: "cURL"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/curl/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 435
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: []
estimated_tokens: 4461
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Understand API error responses, HTTP status codes, and how to handle failures in your integration. This cURL representation preserves HTTP paths and JSON wire names.

### Five questions

#### Q1. Is Errors the right source for this task?

Use this reference for understand api error responses, http status codes, and how to handle failures in your integration. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order.

#### Q2. What does “Do not choose recovery from HTTP status alone” require?

**Do not choose recovery from HTTP status alone.** Read the stable error 
`type`, `fix_code`, and
`code`; use [Error codes](https://studio.inttegro.com/machine/curl/api/error-codes.md) for the
operation-specific meaning.

#### Q3. What does “Retry only when the response recommends it” require?

**Retry only when the response recommends it.** Change invalid input before
retrying, satisfy a missing precondition first, and use exponential backoff
for transient failures. Preserve the original idempotency key and payload
when repeating the same logical write.

#### Q4. What does “Resolve uncertain writes by reading state” require?

**Resolve uncertain writes by reading state.** If a timeout or transport
failure hides the result of a mutation, retry idempotently or use the
resource lookup operation before creating a replacement action.

#### Q5. What does “Keep the request ID for support, but do not show raw developer copy to a shopper” require?

**Keep the request ID for support, but do not show raw developer copy to a
shopper.** Map stable codes to appropriate customer-facing messages in the
application.

## Document 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](https://studio.inttegro.com/machine/curl/api/error-codes.md).

## Turn an API error into the next safe action

The four decision rules are in the machine preamble above.

## 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:

- `200 - OK`

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

- `400 - Bad Request`

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

- `401 - Unauthorized`

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

- `403 - Forbidden`

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

- `404 - Not Found`

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

- `409 - Conflict`

  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](https://studio.inttegro.com/machine/curl/e/payment_transition_conflict.md).

- `422 - Unprocessable Entity`

  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.

- `429 - Too Many Requests`

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

- `500, 502, 503, 504 - Server Errors`

  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.

```json
{
  "error": {
    "cause": "invalid_request_parameter",
    "code": "payment_method_invalid",
    "detail": "the specified payment method could not be used for this order. verify that it belongs to the order customer and is active.",
    "fix_code": "change_request_parameters",
    "message": "payment method could not be used for this order",
    "type": "invalid_request_parameter",
    "url": "https://studio.inttegro.com/e/c-invalid_request_parameter"
  }
}
```

## The error object

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

### Attributes

- `cause` — `string`

  The underlying category of failure—identifies which system or validation rule triggered the error. Common values include [authentication\_failed](https://studio.inttegro.com/machine/curl/e/c-authentication_failed.md), [authorization\_failed](https://studio.inttegro.com/machine/curl/e/c-authorization_failed.md), [invalid\_request\_parameter](https://studio.inttegro.com/machine/curl/e/c-invalid_request_parameter.md), and [missing\_request\_parameter](https://studio.inttegro.com/machine/curl/e/c-missing_request_parameter.md). 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

- `code` — `string`

  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

- `detail` — `string`

  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

- `fix_code` — `string`

  A machine-readable suggestion for how to resolve the error. This field translates the problem into a specific action—for example, [change\_request\_parameters](https://studio.inttegro.com/machine/curl/e/f-change_request_parameters.md), [repeat\_same\_request](https://studio.inttegro.com/machine/curl/e/f-repeat_same_request.md), or [contact\_customer\_support](https://studio.inttegro.com/machine/curl/e/f-contact_customer_support.md).

  - 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

- `message` — `string`

  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

- `type` — `string`

  Categorizes the error into broad classes to help clients determine retry strategies. Common values include [invalid\_request\_parameter](https://studio.inttegro.com/machine/curl/e/t-invalid_request_parameter.md), [transient\_error](https://studio.inttegro.com/machine/curl/e/t-transient_error.md), and [unknown\_error](https://studio.inttegro.com/machine/curl/e/t-unknown_error.md). 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

- `url` — `string`

  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.

- `invalid_request_parameter`

  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 →](https://studio.inttegro.com/machine/curl/e/t-invalid_request_parameter.md)

- `transient_error`

  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 →](https://studio.inttegro.com/machine/curl/e/t-transient_error.md)

- `unknown_error`

  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 →](https://studio.inttegro.com/machine/curl/e/t-unknown_error.md)

## 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.

- `abandon_request`

  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
  →](https://studio.inttegro.com/machine/curl/e/f-abandon_request.md)

- `change_request_parameters`

  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 →](https://studio.inttegro.com/machine/curl/e/f-change_request_parameters.md)

- `contact_customer_support`

  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
  →](https://studio.inttegro.com/machine/curl/e/f-contact_customer_support.md)

- `repeat_same_request`

  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
  →](https://studio.inttegro.com/machine/curl/e/f-repeat_same_request.md)

- `satisfy_precondition`

  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 →](https://studio.inttegro.com/machine/curl/e/f-satisfy_precondition.md)

## 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.

- `authentication_failed`

  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 →](https://studio.inttegro.com/machine/curl/e/c-authentication_failed.md)

- `authorization_failed`

  Your API key is valid but does not allow this operation. Verify that the key
  has the required permissions. [View details →](https://studio.inttegro.com/machine/curl/e/c-authorization_failed.md)

- `invalid_request_parameter`

  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 →](https://studio.inttegro.com/machine/curl/e/c-invalid_request_parameter.md)

- `missing_request_parameter`

  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 →](https://studio.inttegro.com/machine/curl/e/c-missing_request_parameter.md)

- `precondition_unmet`

  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 →](https://studio.inttegro.com/machine/curl/e/c-precondition_unmet.md)

- `unknown`

  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
  →](https://studio.inttegro.com/machine/curl/e/c-unknown.md)