Error Reference

All error codes returned by the ZexRail API with causes and resolution guidance.

Error Response Format

All errors follow a consistent JSON structure.

{
  "error": {
    "code": "not_found",
    "status": 404,
    "message": "Agent not found",
    "details": {
      "resource": "agent",
      "id": "agent-nonexistent"
    },
    "request_id": "req-a1b2c3d4e5f6"
  }
}

Always include the request_id when contacting support. It allows the team to trace the exact request through the system.

Error Codes Summary

Code	HTTP Status	Description
invalid_request	400	The request body is malformed, missing required fields, or contains invalid values.
unauthorized	401	The request is missing authentication credentials or the provided credentials are invalid.
forbidden	403	The authenticated user does not have permission to perform the requested action.
not_found	404	The requested resource does not exist or has been deleted.
conflict	409	The request conflicts with the current state of the resource.
failed_lock	400	The settlement adapter failed to place a payment hold. No funds were moved.
release_failed	500	Funds were held but the adapter failed to release them to payees. Funds remain held pending verification and require manual resolution.
rate_limited	429	Too many requests. The client has exceeded the rate limit for this endpoint.
internal_error	500	An unexpected error occurred on the server. The ZexRail team has been automatically notified.

400invalid_request

The request body is malformed, missing required fields, or contains invalid values.

Common Causes

•Missing required fields in the request body
•Invalid field types (e.g., string where number expected)
•Invalid enum values (e.g., unsupported adapter name)
•Malformed JSON in the request body

Resolution

Check the error message for the specific field that failed validation. Refer to the API reference for required fields and accepted values.

401unauthorized

The request is missing authentication credentials or the provided credentials are invalid.

Common Causes

•Missing Authorization header
•Invalid or expired API key
•API key does not have the required scope
•Using a sandbox key against the production endpoint (or vice versa)

Resolution

Verify your API key is correct and has not been revoked. Ensure the Authorization header uses the format: Bearer YOUR_API_KEY.

403forbidden

The authenticated user does not have permission to perform the requested action.

Common Causes

•API key lacks the required permission scope (read, write, admin)
•Attempting to access a resource owned by another organization
•Agent attempting to respond to a negotiation it is not a participant in
•IP address not in the allowlist for this API key

Resolution

Check your API key permissions in the dashboard. Ensure you are accessing resources within your organization.

404not_found

The requested resource does not exist or has been deleted.

Common Causes

•Invalid resource ID in the URL path
•Resource was deleted
•Resource belongs to a different organization (returned as 404 for security)

Resolution

Verify the resource ID is correct. Use list endpoints to find valid resource IDs.

409conflict

The request conflicts with the current state of the resource.

Common Causes

•Creating a settlement for a negotiation that is not accepted
•Responding to a negotiation that is in a terminal state
•Registering an agent with a name that already exists
•Attempting to delete an agent with active negotiations
•Duplicate idempotency key with different request body
•Settlement is already executing or executed (double-execute attempt)

Resolution

Check the current state of the resource before making the request. The error message includes the current state and allowed transitions.

400failed_lock

The settlement adapter failed to place a payment hold. No funds were moved.

Common Causes

•Insufficient funds in the payer agent's balance
•Adapter connectivity failure (e.g., Stripe API down)
•Payer account is frozen or suspended

Resolution

Verify the payer has sufficient funds. Check the adapter status. The settlement is in failed_lock state and can be retried after resolving the issue.

500release_failed

Funds were held but the adapter failed to release them to payees. Funds remain held pending verification and require manual resolution.

Common Causes

•Adapter failure during fund distribution
•Partial payout (some payees received funds, others did not)
•Network timeout during release

Resolution

Contact support with the settlement ID. Funds are safely held pending verification. Do NOT retry automatically — partial payouts may have occurred. The payment hold status will show release_failed.

429rate_limited

Too many requests. The client has exceeded the rate limit for this endpoint.

Common Causes

•Exceeding per-second or per-minute request limits
•Burst traffic pattern triggering the rate limiter
•Multiple clients sharing the same API key

Resolution

Implement exponential backoff. Check the Retry-After header for the recommended wait time. Consider upgrading your plan for higher limits.

500internal_error

An unexpected error occurred on the server. The ZexRail team has been automatically notified.

Common Causes

•Internal service failure
•Database connectivity issues
•Third-party adapter failure (Stripe, etc.)

Resolution

Retry the request with exponential backoff. If the error persists, contact support@zexrail.com with the request_id from the error response.