Menu
Theme
Open the console
APIAPI version v1
Open the consoleFrançais

Error codes

Every code the API can answer: what it means and what to do about it.

The error object

The body of every error answer: one error object.

Attributes

errorobject
The error.
Child attributes
typeenum
The family of the error. A closed list: a new value is announced in the changelog.
Possible values
  • invalid_request_error
  • authentication_error
  • permission_error
  • rate_limit_error
  • api_error
codeenum
The code of the error, stable: branch on it. A closed list; adding a code is a compatible change, so a client must accept a code it does not know (and act on the HTTP status).
Possible values
  • parameter_invalid
  • parameter_missing
  • parameter_unknown
  • search_query_invalid
  • api_key_invalid
  • plan_feature_missing
  • api_key_scope_missing
  • resource_missing
  • route_missing
  • organization_suspended
  • api_error
  • service_unavailable
  • rate_limit_exceeded
messagestring
An English explanation for a developer. It may change: never branch on it, never show it to an end user as it is.
paramstringnullable
The request parameter at fault (its public name, such as limit or starting_after); null when no parameter is at fault.
doc_urlstring
The page of the documentation that explains the code.
request_idstring
The identifier of the request, also in the Request-Id header: quote it to the support.
Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such event: 'EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30'.",
    "param": "id",
    "doc_url": "https://developer.masterconf.com/errors/codes#resource_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

Error types

invalid_request_error
The request itself is wrong: a parameter is invalid, missing or unknown, the search query does not parse, or the object or route does not exist. Fix the request before sending it again; the same request will fail the same way.
authentication_error
The API key could not be used: it is missing, malformed, unknown, revoked or expired. Check the Authorization header and the key in the console.
permission_error
The key is valid but this call is not allowed: a scope is missing, the plan does not include the feature, or the organization is suspended. Retrying will not help until the key, the plan or the organization changes.
rate_limit_error
Too many requests for this API key in a short time. Wait, then retry with a backoff.
api_error
Something went wrong on the platform's side, not in your request. Retry later with a backoff, and quote the request_id to support if it keeps happening.

Codes

parameter_invalid

Invalid parameter

HTTP status
400

When it happens

A parameter has a value the operation does not accept: a limit outside 1 to 100 (or above 20 with expand[]), a malformed id, an unknown cursor, a field that cannot be expanded, starting_after and ending_before sent together, a non-repeatable parameter sent twice, or an Accept header that excludes application/json. param names the parameter at fault.

What to do

Read param and message, correct that value and send the request again. Check the parameter in the operation's reference.

Operations that can answer it

Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid header 'Accept': this API answers application/json only.",
    "param": "Accept",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

parameter_missing

Missing parameter

HTTP status
400

When it happens

A required parameter is absent, such as event when listing registrations, call_for_papers when listing papers, or query on a search. param names it.

What to do

Add the parameter named by param and send the request again.

Operations that can answer it

Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter 'event'.",
    "param": "event",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

parameter_unknown

Unknown parameter

HTTP status
400

When it happens

The request carries a query parameter the operation does not take. The API never ignores one silently: a misspelt filter would otherwise return unfiltered data. The message lists the parameters the operation accepts.

What to do

Remove the parameter, or fix its spelling against the list in message.

Operations that can answer it

Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "Unknown parameter 'sort' (this route takes no parameter).",
    "param": "sort",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_unknown",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

search_query_invalid

Invalid search query

HTTP status
400

When it happens

The query of a search does not parse: an unknown field, a field used twice, an operator other than : and ~, OR, a value without single quotes, or a ~ value shorter than 3 characters. The message gives the position of the problem.

What to do

Fix the query at the position given in message. Clauses are field:'value' or field~'value', joined by AND .

Operations that can answer it

Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "search_query_invalid",
    "message": "unknown field 'email' at position 53",
    "param": "query",
    "doc_url": "https://developer.masterconf.com/errors/codes#search_query_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

api_key_invalid

Invalid API key

HTTP status
401

When it happens

The Authorization header is missing or is not exactly Bearer mcf_…, or the key is unknown, revoked or expired. Every one of these cases gets the same answer, on purpose. A revoked or expired key is refused within 60 seconds.

What to do

Send Authorization: Bearer <key> exactly, with the key of your organization. If the key was revoked or has expired, an administrator creates a new one in the console (« Intégrations »).

Operations that can answer it

Example error
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is missing, malformed, unknown, revoked or expired.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_key_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

plan_feature_missing

Not included in the plan

HTTP status
402

When it happens

Your organization's plan does not include access to the API, or, for calls for papers and papers, does not include the calls for papers module.

What to do

Ask an administrator of your organization to change the plan. Retrying the request will not help until then.

Operations that can answer it

Example error
{
  "error": {
    "type": "permission_error",
    "code": "plan_feature_missing",
    "message": "The plan of your organization does not include access to the API.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#plan_feature_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

api_key_scope_missing

Missing scope

HTTP status
403

When it happens

The key is valid but lacks the scope the operation needs (events_read, registrations_read or calls_for_papers_read). Expanding an event also needs events_read. The message names the missing scope.

What to do

Use a key that has the scope, or have an administrator create one with it in the console (« Intégrations »).

Operations that can answer it

Example error
{
  "error": {
    "type": "permission_error",
    "code": "api_key_scope_missing",
    "message": "This API key lacks the scope 'events_read'.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_key_scope_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

resource_missing

No such object

HTTP status
404

When it happens

No object of your organization has this id: it does not exist, it was removed, or it belongs to another organization. param names the parameter that carried the id.

What to do

Check the id. If you keep ids in your own system, treat this as the object being gone.

Operations that can answer it

Example error
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such event: 'EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30'.",
    "param": "id",
    "doc_url": "https://developer.masterconf.com/errors/codes#resource_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

route_missing

No such route

HTTP status
404

When it happens

The path matches no operation of the API, for example because of a typo. No operation lists this code: any request can receive it.

What to do

Check the path against the reference. Every operation of the API is a GET under /v1.

Operations that can answer it

Not tied to an operation: any request can receive it.

organization_suspended

Organization suspended

HTTP status
423

When it happens

Your organization is suspended on the platform. While it is, every call with one of its keys gets this answer.

What to do

Contact the platform's support. The calls work again, with the same keys, once the organization is reactivated.

Operations that can answer it

Example error
{
  "error": {
    "type": "permission_error",
    "code": "organization_suspended",
    "message": "The organization is suspended.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#organization_suspended",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

rate_limit_exceeded

Rate limit exceeded

HTTP status
429

When it happens

The key sent more requests than its rate limit allows. The limit is counted per API key by the gateway in front of the API, over fixed one-minute windows; it is currently 600 requests a minute. The answer carries the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. The request never reached the API, so the body's request_id is null.

What to do

Wait for the number of seconds given by X-RateLimit-Reset, then retry with an exponential backoff. Spread large synchronisations over time instead of sending them in bursts. A 429 can also come from the gateway's per-IP protection against bursts, which sends no X-RateLimit-* headers: act on the status and back off the same way.

Operations that can answer it

Answered by the gateway in front of the API, before the request reaches an operation.

api_error

Internal error

HTTP status
500

When it happens

An unexpected error occurred on the platform while answering the request.

What to do

Retry later with an exponential backoff. If it keeps happening, quote the request_id (or the Request-Id header) to support.

Operations that can answer it

Example error
{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An unexpected error occurred. Quote the request id to the support.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_error",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

service_unavailable

Service unavailable

HTTP status
503

When it happens

A service of the platform could not be reached while answering the request. The answer always carries a Retry-After header, in seconds.

What to do

Wait the number of seconds given by Retry-After, then send the same request again. Use a backoff if it fails again.

Operations that can answer it

Example error
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A service of the platform could not be reached: try again shortly.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#service_unavailable",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}