Errors, limits and pagination

The conventions shared by every Merchant API method. The other sections link here.

Successful response format

Methods returning a single entity wrap it in a data field:

{ "data": { "id": 1024, "price": 1990 } }

Some methods additionally return a success: true flag. Lists come back with a pagination wrapper (see Pagination).

HTTP statuses

Error formats

The error body depends on its kind.

Authentication error (401, 403)

{
  "error": "Unauthorized",
  "errorCode": "invalid_credentials",
  "message": "Invalid email or password"
}

Validation error (422)

The messages field is a dictionary where the key is a request field name and the value is the list of messages for that field.

{
  "error": "Validation failed",
  "messages": {
    "0.price": ["The price must be positive"],
    "0.currency": ["Unsupported currency"]
  }
}

Business error (422)

Returned when the request is well formed but cannot be carried out: no active shop is attached to the account, or a product was not found while updating an order.

{
  "error": "Business error",
  "message": "No active shop found"
}

Not found (404)

{ "error": "Not found", "message": "Order not found" }

Rate limit

Some open methods (for example getting a token) are protected against brute force: no more than 10 requests per minute from one IP. Beyond that a 429 is returned with these headers:

The body:

{ "error": "Too many requests", "message": "Too many attempts. Try again later." }

Handle 429 with respect for Retry-After: wait the stated time before retrying.

Pagination

List methods (for example the order list) return data wrapped in data, links and meta:

{
  "data": [ /* list items */ ],
  "links": {
    "first": "https://admin.mobiusapp.io/api/merchant-service/orders/list?page=1",
    "last":  "https://admin.mobiusapp.io/api/merchant-service/orders/list?page=5",
    "prev":  null,
    "next":  "https://admin.mobiusapp.io/api/merchant-service/orders/list?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "last_page": 5,
    "total": 118,
    "path": "https://admin.mobiusapp.io/api/merchant-service/orders/list"
  }
}

The page and page size are set with the page and limit parameters.

Related pages

• Authentication
• Orders
• Merchant API overview