Error Handling Guide

You can check if the Flywire API is up and running on the status page: https://status.flywire.com

 

This error handling guide supports you in dealing with different kinds of errors:

Errors coming from the Flywire API that you as a client can encounter

Errors that your payers can encounter:

API Errors

Format of API Errors

All errors returned by Flywire's API follow IETF's RFC-7807.

Format of an error

The following parameters can be included in an error. Not all parameters are always returned for all errors.

URL to the API documentation. Refer to the documentation and navigate to the relevant section for detailed information about the problem type.

The HTTP status code number.

The HTTP status code number.

A human-readable summary of the problem type.

errors array

Array of objects, a list of the specific errors.

Indicates the location in the request where the error originated.

The parameter that caused the error.

The type of error that occurred.

A message describing the error.

{
    "type": "https://developers.flywire.com",
    "title": "Unprocessable entity",
    "status": 422,
    "detail": "Invalid parameters",
    "errors": [
        {
            "source": "/",
            "param": "payor_id",
            "type": "missing_param",
            "message": "is missing"
        }
    ]
}

 

4xx - API Request Errors

Codes in the 4xx range indicate an error due to the request information provided (e.g. recipient does not exist, an order creation failed, etc.).

  • 400
  • 401
  • 404
  • 422
  • 429

400 Error - Bad Request

When does this happen?

This indicates that the request is not formatted correctly. Possible reasons:

  • missing or invalid parameters

  • non-processable entities

  • method not allowed

  • you tried to create something that already exists

  • any other problem with the structure of the request

What should you do?

Check the details in the error to find more information about the source of the problem and modify your request accordingly.

{
    "type": "https://developers.flywire.com",
    "title": "Bad Request",						
    "status": "400",
    "detail": "Invalid body",
    "errors": [
        {
        "source": "/recipient/fields/id_field",
        "param": "id_field",
        "type": "invalid_param",
        "message": "The provided ID is invalid"
        }
    ]
}

401 Error - Unauthorized Request

When does this happen?

Your API request wasn't authorized. All API requests must contain your API key in the header.

What should you do?

Authenticate your requests as described here: Authenticating your Requests

{
  "type": "https://developers.flywire.com",
  "title": "Unauthorized Request",
  "status": "401",
  "detail": "Invalid or expired token"
}

404 Error - Resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "status": "404",
  "title": "Not Found"
}

422 Error

When does this happen?

Your request was either missing a parameter or a parameter contained an invalid value.

What should you do?

The error response will tell you which parameter is affected. It could be the parameter itself or the value for the parameter.

  1. If there's a missing parameter, check your request if you misspelled the parameter or left it out.

  2. If there's an invalid value, check the validation rules for the value. You'll find descriptions of parameters and their allowed values for each request in this documentation. 

{
    "type": "https://developers.flywire.com",
    "title": "Unprocessable entity",
    "status": 422,
    "detail": "Invalid parameters",
    "errors": [
        {
            "source": "/",
            "param": "payor_id",
            "type": "missing_param",
            "message": "is missing"
        }
    ]
}

429 Error - Rate Limit Exceeded

If you exceed the rate limit, you will receive an 429 error message and you will be blocked from accessing the Flywire API for 10 minutes.

Environment Rate Limit
Flywire API Production

500 requests per minute
Flywire API Sandbox

500 requests per minute

 
{
  "success": false,
  "errors": [
    {
      "code": 1015,
      "message": "You are being rate limited."
    }
  ]
}

5xx - Server Errors

Codes in the 5xx range indicate an error with Flywire's servers.

  • 500
  • 503

500 - Internal Server Error

Communication with the API failed.

When does this happen?

The server is unavailable or an unexpected condition was encountered. This can have various reasons, for example:

  • Authentication issues

  • API being unavailable

  • Server time out (the request took longer than 8 secs)

  • Network issues

What should you do?

Check the following and then try again:

  1. Authentication

    • Ensure that you are using the right API key and it is correctly implemented in the request.

  2. Flywire API Status

  3. Network Connectivity

    • Confirm that your server has a stable internet connection, and no firewall or network issues blocking the connection to the API.

{
  "type": "https://developers.flywire.com",
  "status": "500",
  "title": "Internal Server Error"
}

503 Error- Service Unavailable

When does this happen?

The server is currently unavailable. This is typically a temporary state, often due to maintenance or server overload.

What should you do?

Try the request again after some time.

{
  "type": "https://developers.flywire.com",
  "status": "503",
  "title": "Service Unavailable"

UI Form Errors

Field validation warnings after pre-filling a UI form

What are field validations warnings?

These warnings are returned after you created a Checkout Session and relate the fields of the UI form you want to display.

When are warnings returned?

If the warning array contains warnings, it means that you tried to pre-fill the UI form with invalid values. You can use these warnings to check the data in your system for mistakes.

Are warnings an error?

No, warnings inform you of issues with field values, but you will still receive the URL and can display the form to your payer.

How do the warnings affect the form?

If a drop down field (like country) is affected by invalid values, the field will be empty, meaning no selection from the drop down is made yet. Your payer has to select the value from the drop down manually.

The Checkout Session ID.

This is the session ID you need if you are using Flywire Elements with Smart Rendering or Checkout as Javascript with API.

Smart Rendering means you render Flywire Elements on your website with the help of the Flywire SDK script.

Extensive customization

  • Select which payer fields to display.

  • Customize the appearance, such as fonts and colors.

  • Choose the language.

Responsive layout

Optimized responsive layout for desktop and mobile devices.

Easy event handling

Simply define what should happen in case of success or errors - no need to filter individual postMessages.

The time before the Checkout Session expires in seconds.

hosted_form object

Only relevant when you render the form via iframe. More info:

The hosted-form-URL. This is the URL your iframe displays.

The method (GET).

warnings array

The field where the error occurred.

For a description of all fields and their valid values form see:

errors array

You can decide which information from the response you want to filter out in your backend before passing the URL to your frontend.

The error text.

The error type.

{
"id": "e6bf6f63-46e0-4bd7-9bce-8106c02d0b3f",
"expires_in_seconds": 1800,
"hosted_form": {
	"url": "https://payment-checkout.flywire.com/v1/form?session_id=e6bf6f63-46e0-4bd7-9bce-8106c02d0b3f",
	"method": "GET"
},
"warnings": [
	{
		"source": "email",
		"errors": [
			{
				"text": "must be a valid email",
				"error_type": "invalid_email"
    		}
   		]
  	}
  ]
}

Field validation errors while filling out a UI form

When a payer fills a field of a UI form with wrong values, the field gets highlighted and they see a helpful message why their input isn’t correct.

For a description of all fields and their valid values form see:

Card validation errors after sending card forms

After a payer submits the UI form, the following reasons can cause an error:

  • The card holder’s name or surname is incorrect for the card.

  • CVV is invalid.

  • The authorization failed (the form of authorization depends on the country and bank, for example via 3-D Secure).

If this happens, a new Checkout Session is needed so that the payer can access a new form and try again.