README.markdown in roar-1.0.0.beta2 vs README.markdown in roar-1.0.0

@@ -468,10 +468,43 @@
     property :name
   end
 end
 ```
 
+### Meta Data
+
+Meta data can be included into the rendered collection document in two ways. Please note that parsing the `meta` field is not implemented, yet, as I wasn't sure if people need it.
+
+You can define meta data on your collection object and then let Roar compile it.
+
+```ruby
+module SongsRepresenter
+  # ..
+
+  meta do
+    property :page
+    property :total
+  end
+```
+
+Your collection object has to expose those methods.
+
+```ruby
+collection.page  #=> 1
+collection.total #=> 12
+```
+
+This will render the `{"meta": {"page": 1, "total": 12}}` hash into the JSON-API document.
+
+Another way is to provide the _complete_ meta data hash when rendering. You must not define any `meta` properties in the representer when using this approach.
+
+```ruby
+collection.to_json("meta" => {page: params["page"], total: collection.size})
+```
+
+If you need more functionality (and parsing), please let us know.
+
 ### Usage
 
 As JSON-API per definition can represent singular models and collections you have two entry points.
 
 ```ruby
@@ -637,9 +670,19 @@
 
  ```ruby
 song.get(uri: "http://localhost:4567/songs/1") do |req|
   req.add_field("Cookie", "Yumyum")
 end
+```
+
+### Error handling
+
+In case of a non-2xx response status, `#get` and friends raise a `Roar::Transport::Error` exception. The original response can be accessed as follows.
+
+```ruby
+  song.get(uri: "http://localhost/songs1") # not-existing.
+rescue Roar::Transport::Error => exception
+  exception.response.code #=> 404
 ```
 
 ## XML
 
 Roar also comes with XML support.