Errors

The Gomry API uses standard HTTP status codes to indicate the outcome of a request. Errors return a JSON body with an error field describing the issue.

Error Response Format

{
  "error": "Human-readable error message"
}

For validation errors, additional detail may be included:

{
  "error": "Invalid pagination parameters",
  "details": {
    "fieldErrors": {
      "page_size": ["Number must be less than or equal to 200"]
    }
  }
}

Status Codes

Code	Meaning	When It Happens
`200`	OK	Request succeeded
`400`	Bad Request	Invalid query parameters or request body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	The key lacks a scope (`insufficient_scope`, see Scopes), or would refund an attendee without `payments:read` (`refund_permission_required`)
`404`	Not Found	Resource doesn’t exist or doesn’t belong to your organization
`409`	Conflict	The request can’t go ahead in the resource’s current state, e.g. an unconfirmed refund (see below)
`429`	Too Many Requests	Rate limit exceeded — slow down and retry
`500`	Internal Server Error	Something went wrong on our end
`502`	Bad Gateway	The payment provider refused a refund (`refund_failed`)

Refund Refusals

Rejecting or deleting an attendee who paid refunds them, so it answers with a code in error (plus message, and a quote when there is one) until it can go ahead: 409 refund_confirmation_required, 409 refund_quote_changed, 409 insufficient_balance, 403 refund_permission_required, 502 refund_failed, and 409 ticket_refunded when setting a refunded attendee back. What each means and how to answer it: Update Attendee. Moving the start of an event with paid orders by more than 6 hours opens a refund window, so PATCH /events/{event_id} answers 409 date_change_ack_required (with quote and window_closes_at) until the body carries "acknowledge_refund_window": true, and 403 refund_permission_required for a key without payments read access: Update Event.

Handling Errors

const response = await fetch(url, { headers: { "X-API-KEY": apiKey } });

if (!response.ok) {
  const { error } = await response.json();
  
  switch (response.status) {
    case 401:
      console.error("Authentication failed:", error);
      break;
    case 404:
      console.error("Resource not found:", error);
      break;
    case 429:
      // Retry after a short delay
      await new Promise((r) => setTimeout(r, 2000));
      break;
    default:
      console.error(`API error (${response.status}):`, error);
  }
}

import requests

response = requests.get(url, headers={"X-API-KEY": api_key})

if response.status_code == 429:
    import time
    time.sleep(2)
    # retry...
elif not response.ok:
    error = response.json().get("error", "Unknown error")
    raise Exception(f"API error ({response.status_code}): {error}")

A 404 response does not confirm the resource doesn’t exist — it may belong to a different organization. The API intentionally returns 404 instead of 403 to avoid leaking information about other organizations’ data.

Getting Started

MCP Server

Agentic Commerce

Webhooks

Errors

Errors

Error Response Format

Status Codes

Refund Refusals

Handling Errors

​Errors

​Error Response Format

​Status Codes

​Refund Refusals

​Handling Errors

Errors

Error Response Format

Status Codes

Refund Refusals

Handling Errors