Error codes
Every error the API returns is a problem-details document with a stable code. Its type links to the matching entry below. How errors look, and what to retry, is in the guide to errors.
| Code | Status | What it means and what to do |
|---|---|---|
invalid_request | 400 | A field is missing or wrong. errors lists each one with its path and a message. Fix the request; retrying it unchanged won't help. |
invalid_json | 400 | The body isn't valid JSON. Check quoting, and send Content-Type: application/json. |
invalid_api_key | 401 | No key, a key that isn't shaped like one, or a key that was revoked or expired. Send Authorization: Bearer md4_test_... with an active key from the console. |
insufficient_scope | 403 | The key is valid but lacks the scope this endpoint needs (named in detail). Create a key with that scope. Scopes |
not_found | 404 | No such endpoint, or no record with that id in your organization. Records of other organizations are never visible, so they're "not found" too. |
idempotency_conflict | 409 | That Idempotency-Key was already used, in the last 24 hours, with a different body or endpoint. Use a new key for each new thing you create. Idempotency |
invalid_transition | 409 | Sandbox only: that simulated event doesn't fit the order's current status. The problem's allowed field lists the events that do. The order lifecycle |
not_cancellable | 409 | The order can't be cancelled any more: the sample has reached the lab, or it's already cancelled. |
conflict | 409 | The record changed while we were updating it. Fetch it again, then decide whether to retry. |
limit_reached | 409 | Your organization has the most webhook endpoints it can (10). Delete one you no longer use. |
too_large | 413 | Request bodies are limited to 256 KB. |
rate_limited | 429 | Too many requests with this key. Wait for the number of seconds in Retry-After, then retry; watch RateLimit-Remaining to slow down before this happens. Rate limits |
server_error | 500 | Something failed on our side. Retry with backoff (with the same Idempotency-Key for creates). If it keeps happening, write to developers@md4labs.com with the requestId. |
not_configured | 503 | The sandbox is being set up and isn't ready to take calls. Try again later. |
New codes may be added within v1. Handle an unknown code by its HTTP status.