Skip to main content

Troubleshooting Common API Request Issues

A complete guide to troubleshooting API requests, understanding error responses, and resolving common issues for smoother API usage.

Updated over 2 weeks ago

If your API requests aren’t working as expected, don’t worry, most issues can be identified and resolved quickly by checking a few key points. This guide will help you understand common API errors, why they happen, and what steps you can take to fix them.

You can review the full API documentation in detail using this link.

📌Check Your Network and Endpoint URL

Most common cause: Connectivity issues or incorrect endpoint URLs.
​

What to do:

  • ✅ Make sure you’re connected to the internet.

  • ✅ Verify that you are using the correct base URL and endpoint path as shown in the Business Customer API documentation.

The base URL is your domain with the API or REST subdomain.
For example, if your management console is dispatcher.onro.io, your base URL will be api.onro.io or rest.onro.io.

  • ✅If you’re using a test environment(demo), confirm that the staging or sandbox URL is being used correctly.

  • ✅Try sending a simple GET request (for example, to fetch a customer) to confirm the connection.

Tip: You can test requests using tools like Postman or curl. If this fails, the issue is likely related to your network or URL setup.

📌Headers

Each request must include the required headers to ensure successful authentication and proper communication with the server.

Header

Description

Example

Authorization

Your access token for authentication. Always include the word Bearer before the token.

Authorization: Bearer your_access_token

Content-Type

Defines the format of the request body. For JSON data, use ->

Content-Type: application/json

Accept

Specifies the format of the response you expect from the API.

Accept: application/json

Accept-Language

Sets the preferred language for the response.

Accept-Language: en

Example request:

curl -X GET "https://api.onro.io/business/customers" \      -H "Authorization: Bearer your_access_token" \      -H "Content-Type: application/json" \      -H "Accept: application/json" \      -H "Accept-Language: en"

Common Header-Related Errors

Error

Cause

Solution

401 Unauthorized

Missing or invalid Authorization header, expired access token, or incorrect token format.

Make sure you’ve added Authorization: Bearer your_access_token with a valid token. If it’s expired, generate a new one.

403 Forbidden

The token does not have permission for the requested resource.

Check if the user or driver associated with the token has the correct permissions.

415 Unsupported Media Type

Incorrect or missing Content-Type header.

Set Content-Type: application/json for all JSON-based requests.

406 Not Acceptable

The server cannot provide the requested format.

Ensure Accept: application/json is included in the request headers.

📌Getting an access token

To interact with the Business Customer API, you must first obtain an access token. This token authenticates your requests and ensures that only authorized users or applications can access the API.

Common Errors When Requesting an Access Token

Error Code

Cause

Solution

400 Bad Request

Missing or invalid client_id or client_secret, or malformed request.

Ensure all required parameters are included and correctly formatted according to the API documentation.

403 Invalid Refresh Token

The refresh token used is invalid, expired, or already revoked.

Obtain a new access token using a valid refresh token. Make sure you are using the most recent token issued by the API.

429 Too Many Requests

Exceeding the token request rate limit.

Wait for the duration indicated in the Retry-After header before retrying. Reduce request frequency if possible.

500 Internal Server Error

The server encountered an unexpected issue while processing your request.

Retry after a short delay. If the problem persists, contact support with the request timestamp and details.

Example Request:

POST https://api.onro.io/oauth/token Content-Type: application/json  {   "client_id": "YOUR_CLIENT_ID",   "client_secret": "YOUR_CLIENT_SECRET" }

Tips:

  • Always use the correct Base URL.

  • Include all required headers.

  • Check the response body for error and message fields to identify the exact problem.

📌Use the Response Body for Clues

Every error response includes a message field explaining what went wrong. Always check the response body; it often tells you the exact problem.

Example:

{
  "code": -16,
  "message": "Promo code is not valid",
  "data": {},
  "meta": {
    "stack": "",
    "url": "/api/v1/customer/order/ondemand/calculate-price",
    "method": "POST"
  }
}

By reading this message, you can correct your request without further trial and error.

📌Check Your Request Body and Parameters

Error examples:

  • 400 Bad Request

Possible causes:

  • Missing required fields.

  • Incorrect data types (for example, sending text instead of a number).

  • Invalid JSON format.

  • Some fields in the API have maximum or minimum numeric limits. If you send a value outside the acceptable range, the API will return an error (usually 400 Bad Request) indicating the issue.

What to do:

  • Review the API documentation for the correct schema and required fields.

  • Validate your JSON format before sending.

  • Ensure values like quantities, amounts, or IDs do not exceed these limits.

    Example:

    {
      "code": -400,
      "message": "COD Amount exceeds maximum limit. Please adjust.",
      "data": {},
      "meta": {
        "stack": "",
        "url": "/api/v1/customer/order/ondemand",
        "method": "POST"
      }
    }

📌Monitor Rate Limits

Error example:

  • 429 Too Many Requests

Possible causes:

  • Sending too many requests within a short time window.

  • Not handling retries correctly in your app.

What to do:

  • Check the response headers Retry-After to see how long to wait before resending (usually it takes about 10-15 minutes).

  • Implement exponential backoff in your retry logic.

  • Review your integration to avoid unnecessary repeated calls.

📌Common API Error Responses and what they mean

❌Understanding “Service Unavailable” Error Responses

Sometimes, when making API requests, you may receive an error response like this:

{
  "code": -400,
  "message": "Service unavailable",
  "data": {},
  "meta": {
    "stack": "BadRequest: Service unavailable\n    at PricingService.calculatePickupDelivery (/usr/src/app/rest/dist/components/pricing/common/services/pricing.js:364:19)\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)\n    at async ExpressCustomerOrderController.calculatePickupDelivery (/usr/src/app/rest/dist/controllers/express/customer/order.js:569:45)",
    "url": "/api/v1/customer/order/pickup-delivery/calculate-price",
    "method": "POST"
  }
}

This error is mostly related to the Coordinates

This type of error usually indicates one of the following issues with the coordinates you sent:

  1. Incorrect coordinates – The values may be wrong or invalid.

  2. Latitude and longitude reversed – The API expects coordinates in this order: longitude first, then latitude.
    ​

    Example:

    "pickup": {
        "coordinates": [
            -0.15869881563038823,  // Longitude (West-East)
            51.51268479847148      // Latitude (North-South)
        ]
    }

    • Longitude: -0.15869881563038823 (negative means west of the Prime Meridian)

    • Latitude: 51.51268479847148 (positive means north of the equator)
      ​

    Tip: Reversing these values (latitude first, then longitude) will cause errors or place the location incorrectly.

  3. No active zone – The location you provided is outside any active service zones.

What to do:

  • Verify the coordinates you are sending.

  • Ensure longitude comes before latitude in your request.

  • Check that the coordinates fall within a valid service area.

Correcting any of these will usually resolve the error.

❌Minimum Balance Error when creating scheduled orders

You may encounter an error like this when trying to schedule an order:

{
  "code": -15,
  "message": "You shoud have at least $10,000,000,000 balance to be able to schedule an order.",
  "data": {},
  "meta": {
    "stack": "",
    "url": "/api/v1/customer/order/ondemand",
    "method": "POST"
  }
}

What this means:

  • The API requires that your account have a minimum balance before you can place an order.

  • In this example, you need at least $10,000,000,000 in your account.

How to resolve it:

  1. Check your current account balance.

  2. Ensure you have enough funds to meet the minimum required for scheduling the order.

  3. Once your balance meets the requirement, you can retry the request.

Tip:

  • This is a business rule, not a technical error. The request format and endpoint are correct; the API is simply enforcing a minimum balance policy.

  • If you believe your balance is sufficient but still get this error, contact support and provide the full error response.

📌Checklist Before Contacting Support

If your API request still fails after checking the above, go through this quick checklist:

  1. ✅ Internet connection works.

  2. ✅ Correct API URL and method (GET, POST, etc.).

  3. ✅ Valid authentication token.

  4. ✅ Request body matches required schema.

  5. ✅ Proper headers set (Authorization, Content-Type, etc.).

  6. ✅ Rate limits not exceeded.

  7. ✅ Error response reviewed.

If everything looks fine and the issue persists, contact our support team and include:

  • The request URL

  • The request body

  • The exact response body

We’ll be glad to assist you, and providing this information helps us resolve your issue more quickly.

Did this answer your question?