Error Handling

HTTP Status Codes

Code	Meaning
200	Success
202	Accepted — async confirmation initiated (async flow)
204	Success (no content) — returned for deletes and updates
400	Bad request — invalid parameters or business rule violation
401	Unauthorized — invalid or expired booking session
404	Not found — resource doesn't exist
424	Failed dependency — e.g., availability selection expired
503	Service unavailable — ticketing provider is down or confirmation failed

Error Response Formats

The API does not use a single error response format. Depending on the error source, you may receive one of several different shapes. Your integration should handle all of them.

Format 1: Business Logic Errors (most common)

Returned for known API error codes (reservation failures, ticket validation, provider issues, etc.):

{
    "title": "400 Bad Request",
    "description": "Attractions cannot be purchased together within the same transaction",
    "code": 36,
    "timestamp": "2024-02-06T14:24:02.172544+00:00",
    "exception_id": "965dc1ac60d244b9b9a837a841e45fdd",
    "request_id": "4351f39722a94630aaa64613359d1750"
}

• code — numeric error code from the Known API Error Codes table
• exception_id — share this with Coras support for debugging
• request_id — correlates with server-side logs

Format 2: Validation Errors

Returned when request parameters fail schema validation (e.g., missing required fields, wrong types):

{
    "title": "400 Bad Request",
    "description": "Bad Request",
    "code": null,
    "errors": {
        "email": ["Not a valid email address."],
        "tickets": ["Missing data for required field."]
    }
}

• errors — a map of field names to arrays of validation error messages
• code is null (no numeric error code for validation errors)

Format 3: Standard HTTP Errors

Returned by middleware (auth, content negotiation) and framework-level checks:

{
    "title": "401 Unauthorized",
    "description": "Authorization token required",
    "code": null
}

No timestamp, exception_id, request_id, or errors fields are present.

Format 4: Stripe Errors

Returned when Stripe payment operations fail:

{
    "title": "400 Bad Request",
    "description": "Your card was declined.",
    "code": "card_declined"
}

• code is a string (Stripe error code), not a numeric code

Format 5: Internal Server Errors

Returned for unhandled exceptions:

{
    "title": "500 Internal Server Error",
    "description": "Internal Server Error",
    "code": null
}

Recommended Parsing Strategy

Since formats vary, parse error responses defensively:

1. Always check for title and description — these are present in all formats.
2. Treat code as optional and potentially a string or integer (or null).
3. Check for the errors field to detect validation errors and display field-level messages.
4. Use exception_id (when present) for support requests to Coras.

Known API Error Codes

The table below lists the known error codes. Note that this is not an exhaustive list — additional error codes may be returned. Your integration should handle unknown codes gracefully (e.g., display the description to the user or log it for investigation).

Booking & Ticket Errors (HTTP 400)

Code	Name	Description	Resolution
1	Invalid split	Invalid number of tickets for selected price type	Choose a quantity from the valid_splits array
2	Multipurchase not supported	Cannot buy tickets from multiple price bands	Create separate reservations per price band
24	Multi-currency basket	Basket items must use the same currency	Ensure all reservations use the same currency
25	Missing attendees	Attendees required but not provided	Register attendees via POST /v2/attendees before confirming
26	Invalid pickup point	Pickup ID not from availability response	Use a coras_pickup_id from the availability check response
28	Missing phone verification	Phone number confirmation code required	Call POST /v2/phone-number-verification first
29	Invalid phone code	Confirmation code is incorrect	Prompt user to re-enter the verification code
30	Seat selection not supported	Attraction does not support individual seat sales	Use general admission (omit seats array)
31	Max tickets exceeded	Maximum ticket count reached for reservation	Reduce the number of tickets
32	Multi-row not supported	Seats selected from different rows	Select seats from the same row
36	Incompatible attractions	Attractions cannot be in the same transaction	Complete transactions separately
37	Minimum tickets not met	Below minimum booking size	Select at least min_booking_size tickets
38	Incorrect total ticket count	Total tickets outside allowed range	Ensure total is between min_booking_size and max_booking_size
39	Incorrect price type count	Ticket count for a price type outside allowed range	Adjust to fit the min/max for that price type
40	Invalid exchange rate timestamp	Exchange rate override timestamp too far from current time	Use a more recent exchange rate timestamp
50	Invalid booking fee	Booking fee is invalid (e.g., too low or too high)	Ensure booking fee is a positive number within allowed limits
51	Invalid ticket configuration	Ticket configuration is invalid compared to availability check request	Make sure the same data are sent as in the availability check request
52	Missing attendees for tickets	Attendees must be registered for the number of tickets	Register the correct number of attendees via POST /v2/attendees
53	Updating reservation is not supported	Cannot update an existing reservation	Create a new reservation with the updated details

Provider / Partner Errors (HTTP 503)

Code	Name	Description	Resolution
0	Provider unavailable	Ticketing partner is down	Retry later
4	Connection error	Cannot connect to ticketing partner	Retry later
7	Request failed	Partner request failed	Retry later
8	Cannot confirm	Partner cannot confirm the booking	Retry later; contact Coras support if persistent
9	Cannot create reservation	Partner cannot create the booking	Retry later
11	Auth failed	Partner authentication failed	Retry later; contact Coras support if persistent
12	Request timeout	Partner request timed out	Retry later
14	Unexpected response	Partner returned an unexpected response	Retry later; contact Coras support if persistent
22	Retries exceeded	Max retry attempts reached for partner	Retry later
35	Confirmation pipeline failed	Backend confirmation process failed	Retry later; contact Coras support

Payment / Payment Provider Errors

Code	Name	Description	Resolution
1000	Payment card error	An error occurred with the provided payment card	Display the Stripe description to the user and prompt for a different card or payment method
1001	Payment rate limit error	Too many payment attempts in a short period	Advise the user to wait before trying again
1002	Payment invalid request error	Invalid parameters were sent to the payment provider	Log the error details and display a generic payment error message to the user
1003	Payment authentication error	Authentication with the payment provider failed	Advise the user to check their payment details and try again
1004	Payment API connection error	Network communication with the payment provider failed	Advise the user to check their internet connection and try again
1005	Payment processing error	An error occurred while processing the payment	Advise the user to try again later or contact support if the issue persists
1006	Payment provider error	An unknown error occurred during payment processing	Advise the user to try again later or contact support if the issue persists
1007	Payment error parsing error	An error occurred while parsing the payment provider's error response	Log the full response for debugging and display a generic payment error message to the user

Availability Errors (HTTP 424)

Code	Name	Description	Resolution
33	Selection expired	Availability selection timed out	Re-check availability and try again

Common Error Handling Patterns

Scenario	Action
401 Unauthorized	Booking session expired — create a new one
Any code 0–22 (provider errors)	Display "temporarily unavailable" and offer retry
Code 1, 31, 37, 38, 39 (ticket count errors)	Guide user to adjust ticket selection
Code 36 (incompatible attractions)	Remove conflicting reservations or complete separately
Code 33 (selection expired)	Re-run availability check before reserving
Unknown error code	Log the full response and display the description to the user