Errors

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

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

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

Your API key lacks permission to perform this operation. This usually means your application doesn't have access to the requested resource or action.

The requested resource doesn't exist. Verify the resource ID is correct and belongs to your application.

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.

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

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

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

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

A comprehensive explanation of what went wrong, including context about the operation and actionable guidance for resolution. This field provides more depth than message and often includes specific values from your request that caused the problem.

• 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

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

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

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

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

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 →

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 →

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 →

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 →

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 →

The error requires manual intervention from Zebo 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 →

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 →

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 →

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 →

Your credentials were authenticated successfully but lack permission to perform the requested operation. This typically means the resource belongs to a different application or your API key's permissions don't include the attempted action. Verify you're accessing resources owned by your application. View details →

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 →

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 →

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 →

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 →