Reading one API operation in our docs: permission, parameters, examples, responses and errors

The short answer: every operation in the documentation has the same sections, in the same order: Authentication, Parameters, Request body (when there is one), Examples, Responses, Response fields and Errors. Once you have read one, the rest go quickly.

The sections, one by one

Section	What it says	What to look out for
Authentication	Whether the operation needs a key and which permission the key must have.	Without that permission the API answers 403 with the code insufficient_scope.
Parameters	A table with Name, In, Type, Required and Description.	"In" tells you whether the value goes in the path, in the query (after the ?) or in a header.
Request body	The JSON fields to send, with their type and whether they are required.	Only shown on operations that create or change something.
Examples	The same request in curl, PHP, Python and JavaScript.	The key always comes from the RLX_API_KEY variable, never written in the code.
Responses	One tab per status code, with a JSON example.	A successful response carries data and meta; an error carries error.
Response fields	What each returned field means.	Handy for deciding what to keep in your own system.
Errors	A table with Status, Code and Meaning.	The code never changes; the message changes with the language.

Three details that make a difference

1	On POST requests you will see the optional Idempotency-Key header. It lets you repeat the request, after a network failure for example, without doing it twice.

2	Some operations answer 202 with an action_id, because the work carries on after the response. You follow the result with GET /v1/actions/{id} instead of repeating the request.

3	Lists come in pages. If the operation returns a list, the Pagination section of the API rules explains how to read all of it.

Response examples are only examples. The service numbers, domains and values in your account are different. Never copy an identifier from an example into a real request.

Want error messages in Portuguese? Send the Accept-Language: pt header. Without it, messages come in English.

What each error code means, and which ones are worth retrying, is in Errors, in the API rules.

Before you handle errors in your program, read the full table of codes.

See the error codes

Categories

Categories

Support

The sections, one by one

Three details that make a difference

Categories

Categories

Support

Reading one API operation in our docs: permission, parameters, examples, responses and errors

The sections, one by one

Three details that make a difference

Related Articles

Generate Password