Guides

Request/Response

Top-level overview of Request and Response objects/codes used within Falcon API

Suggest Edits

Request Type

Falcon API HTTPS request support is limited to a subset of RFC 2616 for Sandbox, UAT, and Production APIs.

Request TypeDescription
GETMost common and widely used methods within API. Falcon methods use GET to retrieve relevant details within the system. e.g. Get User Transactions
POSTCommon information insertion within the Falcon system is handled through POST. e.g. Add User.
PATCHA conventional method to update any given data through the API. e.g. Update User
DELETEThis request type removes an unrequired resource from the database. e.g., Block Card basically disables or removes the active card from the Falcon system.
PUTThis has a similar effect as 'POST'; however, PUT is defined to assume idempotency, so if you PUT an object twice, it should have no additional effect. e.g. Enable / Disable Card

Response Codes

Falcon API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • 200 OK indicates a successful transaction.
  • 403 Forbidden relates to Acces Denied Config Issue.
  • 401 Unauthorized occurs when invalid credentials are provided.
  • 400 Bad Request is for invalid data passed onto the request.
  • 500 Internal Server Error occurs when anything goes wrong in CargoDocs API.
  • 503 Service Unavailable is a default HTTP response in case of a non-responsive service.

Response Error Object

A standard error response is passed against an endpoint throughout. A typical Error response object looks like this:

{
    "errors": [
        {
            "code": 5050,
            "field": null,
            "message": "Authorization header contains an unacceptable value"
        }
    ]
}

code: This is Falcon's internal error code. Do review Falcon Internal Error Messages for more details over the error codes and relevant messages based on different scenarios a developer might face over the course of development.
field: This represents the field name within the Product UI [If available].
message: Readable error for a receiver.

❗️

Graceful Error Handling

Our libraries raise exceptions for many reasons, such as parameters issues, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

🚧

Additional HTTP Response Codes

Other standard HTTP errors may be generated by our stack and not directly from our API. Here are the categories of possible Standard HTTP response codes.

1xx: Communication transfer protocol-level information.
Informational

2xx: This indicates that the client's request was accepted successfully.
Success

3xx: Indicates that the client must take some additional action to complete their request.
Redirection

4xx: This category of error status codes points to the clients.
Client Error

5xx: This category of error is related to server exceptions due to internal incapability to perform the request. The user is advised to contact Falcon Support.
Server Code

For more information please refer https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Updated almost 3 years ago