Getting started with the API: Error handling

  • Updated

The API’s response sets the correct HTTP status code from the list of status codes. In this post we’re digging a little deeper into the different types of status codes and how you should interact with them.

As a rule of thumb:

  • 2xx range: we’re all doing great
  • 4xx range: your application might be doing something wrong
  • 5xx range: our application might be doing something wrong

200

The 200 ok status code tells you that everything was successful and you can rest easy.

202

The 202 accepted status code tells you that we received the request, but have not acted upon.

  • MAXIMUM_CUSTOM_BARCODES_AMOUNT_EXCEEDED, MAXIMUM_EXTERNAL_CODES_AMOUNT_EXCEEDED, MAXIMUM_PROMOTION_CODES_AMOUNT_EXCEEDED: The file you're uploading will put you above the code limit for your event.
  • MAXIMUM_UPLOAD_LIMIT_EXCEEDED_CUSTOM_BARCODES, MAXIMUM_UPLOAD_LIMIT_EXCEEDED_EXTERNAL_CODES, MAXIMUM_UPLOAD_LIMIT_EXCEEDED_PROMOTION_CODES: The file you are trying to upload contains more than the code limit per event.

401

The 401 unauthorized status code is thrown when you are performing a request that your access token can not fulfill.

If you are encountering this, review the authentication section on the getting started page.

403

The 403 forbidden status code tells you that you are not playing by the rules of the platform. The origin of this problem can be a lot of things, refer to the actual error message to understand what is going on.

Some examples are:

  • FORBIDDEN_TO_DELETE_TICKET_TYPE_WITH_TICKETS: you can’t delete a ticket type that contains booked tickets.
  • FORBIDDEN_TOO_MANY_TICKETS_FOR_EVENT: the purchase has reached its limits for that event.
  • FORBIDDEN_TICKET_SHOULD_HAVE_PROMO_CODE: the ticket required a promotion code to be booked.
  • FORBIDDEN_REMOVING_CONFIRMED_SUPERVISED_PAYMENT: you are not allowed to remove a supervised payment.
  • FORBIDDEN_DUPLICATE_EMAIL: The customer's email cannot be used more than once to register.
    ...

404

The 404 not found status code can be thrown on almost any resource type. When you encounter a 404, you should review the following:

  • Check the error, it tells you which specific resource in your query can not be found.
  • Is the ID that you provided the correct ID for that resource?
  • Is the ID that you provided related to the resource hierarchically above in your request. E.g. is the provided ticket type ID related to the event you specified above.
  • Do you or the purchase have access to the resource? E.g are you requesting events from an organizer you have access to. Are you requesting ticket types from a distribution your purchase has access to?

413

The 413 payload too large status code can be encountered when your file upload exceeds the maximum size.

5xx

When you encounter a 5xx error, something serious has gone wrong. This is the part where you might want to create a support ticket. But hold on, you might also identify the problem by yourself.

In the cases of 502 bad gateway and 503 service unavailable the application might be unhealthy and we are definitely already aware of this.

Some understandable cases of a 500 error are:

  • BAS_REQUEST_FAILED: our Best Available Service API could not find any seats. The seat plan does not have enough seats OR was miss configured causing it to look like it was sold out.
  • CURRENCY_MISSMATCH_IN_PSP_CALLBACK: something has gone wrong with currencies when paying in the external payment provider.
  • MANDRILL_MAIL_ERROR: the Mandrill mail service might be unavailable.
  • FAILED_TO_CALCULATE_FEES: there might be a missing or wrong configuration of fees.
  • PRICE_MISSMATCH_IN_PSP_CALLBACK: the paid amount is not what was expected by the application

Exploring the API

Now that you understand the basics, it’s time to take a look at our schemas. You can find them with inline documentation at the right hand side of our GraphiQL tool!

The Oxynade platform and its API is quite big, so we’re splitting up the API documentation into different topics:

Happy integrating!

Related articles