Handling API Responses

Dibsy API always sends responses in a JSON format, a standard for data communication interpretable by both humans and machines. Along with this, a status-code, that shows whether the request is successful or not. If it has failed, you can identify it by the HTTP status code and the message about what went wrong.

We closely follow the HTTP specification and return relevant HTTP status codes. Additionally, the body of the response will contain valid JSON with further descriptions of the error.

The response types

The following classes of codes are relevant to the Dibsy API:

• A code in the 2xx range comes with a Dibsy API response indicating success.
• A code in the 4xx range is an error code returned from the Dibsy API where the client (your side) seems to be causing the error.
• A code in the 5xx range is an error caused by the server (Dibsy’s responsibility). So caused by the Dibsy API or it is infrastructure-related. In the rare case you get this type of error, something is wrong with the Dibsy API. The errors should subside without your mediation.

A successful request

An HTTP status 200 OK, 201 Created or 204 No Content is issued whenever your request was a success. You see this type of response in our examples like this one below where we successfully retrieve a payment.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "pt_oDwrePlFoRwDXYVWj9",
    "resource": "payment",
    "mode": "live",
    "amount": {
        "value": "5.00",
        "currency": "QAR"
    },
    "description": "Order #1236",
    "method": "creditcard",
    "redirectUrl": "https://example.com/order/12345",
    "webhookUrl": "https://example.org/webhook/12345",
    "status": "open",
    "organizationId": "300000",
    "sequenceType": "oneoff",
    "metadata": {
        "order_id": "1236"
    },
    "createdAt": "2021-12-31T11:05:20.026197445",
    "expiresAt": "2021-12-31T11:20:20.025",
    "_links": {
        "self": {
            "href": "http://api.dibsy.one/v2/payments/pt_oDwrePlFoRwDXYVWj9",
            "type": "application/hal+json"
        },
        "checkout": {
            "href": `https://checkout.dibsy.one/pt_oDwrePlFoRwDXYVWj9`,
            "type": "text/html"
        },
        "dashboard": {
            "href": "https://dashboard.dibsy.one/payments/pt_oDwrePlFoRwDXYVWj9",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://api.dibsy.dev/#operation/Create%20Payment",
            "type": "text/html"
        }
    }
}

Examples of error responses

The HTTP status 401 Unauthorized Request indicates missing or incorrect authorization to execute the desired action.

HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json

{
    "status": 401,
    "title": "Unauthorized Request",
    "details": "Missing authentication or failed to authenticate."
}

Another error that occurs often is the well-known HTTP status 400 Bad Request, which indicates your request object contains syntax errors:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "status": 400,
    "title": "Bad Request",
    "details": "The server could not understand the request due to invalid syntax."
}

All possible status codes

Code	Title	Description
201	Created	The entity was created successfully.
204	No Content	The requested entity was canceled / deleted successfully.
400	Bad Request	The Dibsy API was unable to understand your request. There might be an error in your syntax.
401	Unauthorized	Your request was not executed due to failed authentication. Check your API key
403	Forbidden	You do not have access to the requested resource.
404	Not Found	The object referenced by your URL does not exist.
405	Method Not Allowed	You are trying to use an HTTP method that is not applicable on this URL or resource. Refer to the Allow header to see which methods the endpoint supports.
415	Unsupported Media Type	Your request’s encoding is not supported or is incorrectly understood. Please always use JSON.
422	Unprocessable Entity	We could not process your request due to another reason than the ones listed above. The response usually contains a field property to indicate which field is causing the issue.
429	Too Many Requests	Your request has hit a rate limit. Please wait for a bit and retry.
500	Internal Server Error	An internal server error occurred while processing your request. Our developers are notified automatically, but if you have any information on how you triggered the problem, please contact us.
502	Bad Gateway	The service is temporarily unavailable, either due to calamity or (planned) maintenance. Please retry the request at a later time.
503	Service Unavailable	The service is temporarily unavailable, either due to calamity or (planned) maintenance. Please retry the request at a later time.
504	Gateway Timeout	Your request is causing an unusually long process time.