Error Handling

This guide covers how to handle errors from the Mobiledock API, including HTTP status codes, GraphQL error responses, and common troubleshooting steps.

HTTP status codes

Success codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully

Client error codes

Code	Meaning	Action
400 Bad Request	Invalid payload or parameters	Check the response body for details
401 Unauthorized	Missing or invalid token	Verify your Authorization header
403 Forbidden	Token lacks the required permission	Add the permission in the Integration Hub
404 Not Found	Resource does not exist	Verify the URL and resource ID
429 Too Many Requests	Rate limit exceeded	Retry with exponential backoff

Server error codes

Code	Meaning	Action
500 Internal Server Error	Unexpected server error	Retry after a short delay; contact support if persistent
503 Service Unavailable	Service temporarily down	Retry after a short delay

GraphQL errors

GraphQL requests always return HTTP 200, even when the query contains errors. Check the errors array in the response:

{
  "data": null,
  "errors": [
    {
      "message": "You do not have permission to perform this action.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["bookingsV2"]
    }
  ]
}

Common GraphQL errors

Error message	Cause	Fix
”You do not have permission”	Token lacks required permission	Add the permission to your token
”Variable … of type … was not provided”	Missing required argument	Include all required arguments
”Cannot query field … on type …”	Requesting a field that doesn’t exist	Check the schema for available fields
”Argument … has invalid value”	Wrong type for an argument	Verify argument types against the schema

REST API errors

REST endpoints return standard HTTP status codes. Error details are in the response body:

{
  "error": "Validation failed",
  "details": [
    "Field 'direction' must be 'Inbound' or 'Outbound'"
  ]
}

Debugging strategies

1. Check the response body — error responses almost always include a message explaining what went wrong.

2. Verify your token — make a simple query like { bookings(count: 1) { results } } to confirm your token is valid.

3. Check permissions — if you get a 403 or a permission error in GraphQL, verify your token’s permissions in the Integration Hub.

4. Validate your payload — for REST endpoints, ensure your JSON is valid and fields match the expected types.

5. Retry transient errors — for 429, 500, and 503 responses, implement retry logic with exponential backoff:

JavaScript

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response;

    // Don't retry client errors (except 429)
    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
      throw new Error(`Client error: ${response.status}`);
    }

    if (attempt === maxRetries) {
      throw new Error(`Failed after ${maxRetries} retries: ${response.status}`);
    }

    const delay = Math.pow(2, attempt) * 1000;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}

Getting help

If you encounter persistent errors that you cannot resolve, contact assistance@mobiledock.com with:

• The full request (URL, method, headers — excluding your token — and body)
• The full response (status code and body)
• The timestamp of the request